# General

General methods are functions that can't be assigned to a specific table or header and are thus part of the main DotNetPE class.

# Metadata table existence

metadata_table_exists(name: str) -> bool

Checks if a metadata table exists based on its name.

Parameters:

name Name of the table

Return value:

True or False

Example:

# Import class DotNetPE from module dotnetfile
from dotnetfile import DotNetPE

# Create an instance of DotNetPE with the file path as a parameter
dotnet_file = DotNetPE('/Users/<username>/my_dotnet_assembly.exe')

# Check if table "MethodDef" exists in .NET assembly and print out result
if dotnet_file.metadata_table_exists('MethodDef'):
    print('Table exists.')
else:
    print('Table does not exist.')

# Get existent metadata tables

existent_metadata_tables() -> List[str]

Get a list of existent metadata tables.

Parameters:

Return value:

List with metadata table name strings

Example:

# Import class DotNetPE from module dotnetfile
from dotnetfile import DotNetPE

# Create an instance of DotNetPE with the file path as a parameter
dotnet_file = DotNetPE('/Users/<username>/my_dotnet_assembly.exe')

# Get all existent metadata tables of the assembly
available_tables = dotnet_file.existent_metadata_tables()

# Print out each table name
for table in available_tables:
    print(f'{table}')

# Native image check

is_native_image() -> bool

Check if assembly is a native image.

Native images are .NET files that are created with the Windows Native Image Generator Ngen.exe. This tool creates a precompiled native version of a .NET assembly which can be seen as a cached version of the original file. Such a file already contains the native code that is usually created by the JIT compiler at runtime. Thus, these samples are often faster in execution. Consequentially, native images are platform dependant. Also, a disadvantage of native images is that they are much bigger size of the file compared to the original version.

Native Image Generator

https://docs.microsoft.com/en-us/dotnet/framework/tools/ngen-exe-native-image-generator

Usually, native images have the import table stripped and contain an additional section. Therefore, these files are not executable on their own and have to be executed in a special way. However, it is not documented how this happens nor how the image creation itself is done. Also, while you can manually create a native image of your .NET file, there is the Windows service called Native Image Service and starting from Windows 8 and .NET Framework 4.5 the Windows Image Task which seem to automatically create them. Again, how and on what conditions this happens is not documented.

Native Image Service

https://docs.microsoft.com/en-us/dotnet/framework/tools/ngen-exe-native-image-generator#native-image-service

Native Image Task

https://docs.microsoft.com/en-us/dotnet/framework/tools/ngen-exe-native-image-generator#native-image-task

Parameters:

Return value:

True or False

Example:

# Import class DotNetPE from module dotnetfile
from dotnetfile import DotNetPE

# Create an instance of DotNetPE with the file path as a parameter
dotnet_file = DotNetPE('/Users/<username>/my_dotnet_assembly.exe')

# Print out if assembly is a native image
print(f'Is a native image (precompiled) created by Ngen: {dotnet_file.is_native_image()}')

# Mixed assembly check

is_mixed_assembly() -> bool

Check if assembly is a mixed assembly.

Mixed assemblies are .NET files that have both managed and unmanaged code. Compared to normal .NET assemblies, they have more than just the one imported function _CoreExeMain (EXE) or _CorDllMain (DLL) from mscoree.dll on the native side. But also the managed side looks much different with a plethora of initialization namespace, types and methods.

Mixed assemblies

https://docs.microsoft.com/en-us/cpp/dotnet/mixed-native-and-managed-assemblies

These files are normally created with Visual C++ and the C++/CLI extension. C++/CLI is some sort of dialect of C++ created for the production of .NET assemblies with the C++ compiler.

C++/CLI extension

https://docs.microsoft.com/en-us/cpp/dotnet/dotnet-programming-with-cpp-cli-visual-cpp

Usually, you can find the namespaces <CrtImplementationDetails> and <CppImplementationDetails> in mixed assemblies, but there are also exceptions. You can also build mixed assemblies "manually". An example can be found as part of an open-source code for CVE-2019-18935:

CVE-2019-18935 payload

https://github.com/noperator/CVE-2019-18935/blob/master/build-dll.bat

The example shows how to use an empty dummy C# file for the managed part and shellcode for the unmanaged one. The result is a .NET assembly with no managed code and the whole functionality contained in the native part.

Parameters:

Return value:

True or False

Example:

# Import class DotNetPE from module dotnetfile
from dotnetfile import DotNetPE

# Create an instance of DotNetPE with the file path as a parameter
dotnet_file = DotNetPE('/Users/<username>/my_dotnet_assembly.exe')

# Print out if assembly is a mixed assembly
print(f'Is a .NET mixed assembly (managed + native code): {dotnet_file.is_mixed_assembly()}')

# Native entry point existence

has_native_entry_point() -> bool

Check if assembly has a native entry point.

A .NET assembly that has a native entry point is always a mixed assembly.

Parameters:

Return value:

True or False

Example:

# Import class DotNetPE from module dotnetfile
from dotnetfile import DotNetPE

# Create an instance of DotNetPE with the file path as a parameter
dotnet_file = DotNetPE('/Users/<username>/my_dotnet_assembly.exe')

# Print out if assembly has a native entry point
print(f'Has a native entry point: {dotnet_file.has_native_entry_point()}')

# Windows Forms app check

is_windows_forms_app() -> bool

Check if assembly is a Windows Forms app.

A Windows Forms app is a .NET assembly that uses the Windows Forms GUI class library:

Windows Forms

https://docs.microsoft.com/en-us/dotnet/desktop/winforms

Parameters:

Return value:

True or False

Example:

# Import class DotNetPE from module dotnetfile
from dotnetfile import DotNetPE

# Create an instance of DotNetPE with the file path as a parameter
dotnet_file = DotNetPE('/Users/<username>/my_dotnet_assembly.exe')

# Print out if assembly is a Windows Forms app
print(f'Is a Windows Forms app: {dotnet_file.is_windows_forms_app()}')

# Reference assembly check

is_reference_assembly() -> bool

Check if assembly is a reference assembly.

Reference assemblies are special .NET assemblies that only contain metadata necessary to show the library's public API structure. These assemblies don't contain any managed code:

Reference Assemblies

https://learn.microsoft.com/en-us/dotnet/standard/assembly/reference-assemblies

Parameters:

Return value:

True or False

Example:

# Import class DotNetPE from module dotnetfile
from dotnetfile import DotNetPE

# Create an instance of DotNetPE with the file path as a parameter
dotnet_file = DotNetPE('/Users/<username>/my_dotnet_assembly.exe')

# Print out if assembly is a Windows Forms app
print(f'Is reference assembly: {dotnet_file.is_reference_assembly()}')

# Get stream names

get_stream_names() -> List[str]

Get a list of stream names.

Parameters:

Return value:

A list with stream names

Example:

# Import class DotNetPE from module dotnetfile
from dotnetfile import DotNetPE

# Create an instance of DotNetPE with the file path as a parameter
dotnet_file = DotNetPE('/Users/<username>/my_dotnet_assembly.exe')

# Get list of stream names
stream_names = dotnet_file.get_stream_names()

# Print out each stream name
for stream_name in stream_names:
    print(f'\t{stream_name}')

# Resources check

has_resources() -> bool

Check if assembly has resources.

Parameters:

Return value:

True or False

Example:

# Import class DotNetPE from module dotnetfile
from dotnetfile import DotNetPE

# Create an instance of DotNetPE with the file path as a parameter
dotnet_file = DotNetPE('/Users/<username>/my_dotnet_assembly.exe')

# Print out if assembly has resources
print(f'Has .NET resources: {dotnet_file.has_resources()}')

# Get resources

get_resources() -> List[Dict]

Get .NET (sub-)resources data and information.

Parameters:

Return value:

The resulting dictionaries have the following keys and values :

Name str Resource name
Visibility str Resource visibility. Options:
- public
- private
- unknown
Size int Resource size
Data bytes Resource data
NumberOfSubResources int Number of sub-resources
SubResources List[Dict] Sub-resources:
- Name str Sub-resource name
- Type str Sub-resource type. Options:
  - Null
  - String
  - Boolean
  - Char
  - Byte
  - SByte
  - Int16
  - UInt16
  - Int32
  - UInt32
  - Int64
  - UInt64
  - Single
  - Double
  - Decimal
  - DateTime
  - Timespan
  - ByteArray
  - Stream
  - UserType
- TypeDetails Dict Sub-resource type details:
  - TypeEx str Sub-resource detailed type information
  - TypeCode int Sub-resource type code. Options:
    - 0 (Null)
    - 1 (String)
    - 2 (Boolean)
    - 3 (Char)
    - 4 (Byte)
    - 5 (SByte)
    - 6 (Int16)
    - 7 (UInt16)
    - 8 (Int32)
    - 9 (UInt32)
    - 10 (Int64)
    - 11 (UInt64)
    - 12 (Single)
    - 13 (Double)
    - 14 (Decimal)
    - 15 (DateTime)
    - 16 (Timespan)
    - 32 (ByteArray)
    - 33 (Stream)
    - 64 (UserType)
- Size int Sub-resource size
- Data bytes Sub-resource data

Example:

# Import class DotNetPE from module dotnetfile
from dotnetfile import DotNetPE

# Create an instance of DotNetPE with the file path as a parameter
dotnet_file = DotNetPE('/Users/<username>/my_dotnet_assembly.exe')

# Get resource data
resource_data = dotnet_file.get_resources()

# Print out resource and subresource data
for data in resource_data:
    for resource_item in data.items():
        if resource_item[0] == 'SubResources':
            if resource_item[1]:
                print(f'Sub-resources:')
                for sub_resource in resource_item[1]:
                    for sub_resource_item in sub_resource.items():
                        print(f'\t{sub_resource_item[0]}: {sub_resource_item[1]}')
                    print('\t---')
        else:
            print(f'{resource_item[0]}: {resource_item[1]}')
    print('---')

# Get runtime target version

get_runtime_target_version() -> str

Get the .NET runtime target version of the assembly.

The .NET runtime (CLR) has its own version number beside .NET Framework/5/...:

.NET Framework versions and dependencies

https://docs.microsoft.com/en-us/dotnet/framework/migration-guide/versions-and-dependencies

Parameters:

Return value:

Runtime target version string

Example:

# Import class DotNetPE from module dotnetfile
from dotnetfile import DotNetPE

# Create an instance of DotNetPE with the file path as a parameter
dotnet_file = DotNetPE('/Users/<username>/my_dotnet_assembly.exe')

# Print out CLR target version of assembly
print(f'.NET runtime target version: {dotnet_file.get_runtime_target_version()}')

# Get number of streams

get_number_of_streams() -> int

Get the number of metadata streams.

Parameters:

Return value:

Number of streams

Example:

# Import class DotNetPE from module dotnetfile
from dotnetfile import DotNetPE

# Create an instance of DotNetPE with the file path as a parameter
dotnet_file = DotNetPE('/Users/<username>/my_dotnet_assembly.exe')

# Print out number of streams
print(f'Number of streams: {dotnet_file.get_number_of_streams()}')

# Get referenced libraries

get_all_references() -> List[str]

Get a list of all referenced libraries. This includes system, 3rd party and unmanaged libraries.

Parameters:

Return value:

List with library name strings

Example:

# Import class DotNetPE from module dotnetfile
from dotnetfile import DotNetPE

# Create an instance of DotNetPE with the file path as a parameter
dotnet_file = DotNetPE('/Users/<username>/my_dotnet_assembly.exe')

# Get all referenced libraries of the assembly
referenced_libraries = dotnet_file.get_all_references()

# Print out each library name
for library in referenced_libraries:
    print(f'{library}')

# Get #Strings stream strings

get_strings_stream_strings() -> List[str]

Get all strings from the #Strings stream.

The #Strings heap contains all the names of the assembly, namespaces, types and members.

Parameters:

Return value:

List with #Strings stream strings

Example:

# Import class DotNetPE from module dotnetfile
from dotnetfile import DotNetPE

# Create an instance of DotNetPE with the file path as a parameter
dotnet_file = DotNetPE('/Users/<username>/my_dotnet_assembly.exe')

# Get all strings of the #Strings stream
strings_stream_strings = dotnet_file.get_strings_stream_strings()

# Print out each library name
for string in strings_stream_strings:
    print(f'{string}')

# Get #US stream strings

get_user_stream_strings() -> List[str]

Get all strings from the #US stream.

The #US heap contains all strings directly defined by the programmer in method code. The strings are stored in Unicode format.

Parameters:

Return value:

List with #US stream strings

Example:

# Import class DotNetPE from module dotnetfile
from dotnetfile import DotNetPE

# Create an instance of DotNetPE with the file path as a parameter
dotnet_file = DotNetPE('/Users/<username>/my_dotnet_assembly.exe')

# Get all strings of the #US stream
us_stream_strings = dotnet_file.get_user_stream_strings()

# Print out each library name
for string in us_stream_strings:
    print(f'{string}')

# Get #Strings stream string

get_string(string_address: int) -> str

Get a string from the #Streams stream of an assembly. This includes overlapping strings which are part of other strings, e.g. MyString in ThisIsMyString.

This method is more like an internal one, but might be still useful in some situations.

Parameters:

string_address Address/index of the string in the #Strings stream

Return value:

#Strings stream string

Example:

# Import class DotNetPE from module dotnetfile
from dotnetfile import DotNetPE

# Create an instance of DotNetPE with the file path as a parameter
dotnet_file = DotNetPE('/Users/<username>/my_dotnet_assembly.exe')

# Print out string with index 10
print(f'String at index 10: {dotnet_file.get_string(10)}')

# Get #US stream string

get_user_string(string_address: int) -> str

Get a string from the #US stream of an assembly.

This method is more like an internal one, but might be still useful in some situations.

Parameters:

string_address Address/index of the string in the #US stream

Return value:

#US stream string

Example:

# Import class DotNetPE from module dotnetfile
from dotnetfile import DotNetPE

# Create an instance of DotNetPE with the file path as a parameter
dotnet_file = DotNetPE('/Users/<username>/my_dotnet_assembly.exe')

# Print out #US string at index 10
print(f'#US stream string at index 10: {dotnet_file.get_user_string(10)}')

# Get hash from strings

get_hash(hash_type: Type.Hash, string_list: List) -> str

Get a MD5, SHA-1 or SHA-256 hash from a list of strings.

This method can be useful in conjunction with an MSIL disassembler to resolve a token string. For example, you want to get the corresponding string of the token used by a ldstr opcode as part of a malware configuration extractor.

Parameters:

hash_type Hash type ( Type.Hash.MD5 , Type.Hash.SHA1 or Type.Hash.SHA256 )
string_list List with strings

Return value:

Hash as a string

Example:

# Import class DotNetPE from module dotnetfile
from dotnetfile import DotNetPE

# Create an instance of DotNetPE with the file path as a parameter
dotnet_file = DotNetPE('/Users/<username>/my_dotnet_assembly.exe')

# Get all strings from the #US stream (see below)
us_stream_strings = dotnet_file.get_user_stream_strings()

# Print out string with index 10
print(f'SHA-256 hash of all #US stream strings: {dotnet_file.get_hash(dotnet_file.Type.Hash.SHA256, us_stream_strings)}')

# Get token string(s)

get_token_strings(token_string: str) -> Optional[Union[Struct.StringToken, Struct.TableToken]]

Get all strings from a token that is passed as a hex string in the form 0x.... A token is an identification entity that can either encode the TID (table identifier/index) and the RID (record index) of certain tables or identifies a string in the #US stream. It is a 4-byte unsigned integer with the most significant byte encoding the table index (or #US stream) and the remaining 3 bytes are the RID (or #US stream string offset). In case the token is a table token, the method returns all referenced strings in the table row the token indexes.

Parameters:

token_string Token (hexadecimal string "0x...")

Return value:

The result can be a Struct.StringToken in case the token encodes a string (#US stream) or a Struct.TableToken if it leads into a table.

A returned Struct.StringToken dataclass object has the following values:

stream str Stream name (#US stream)
string_address int String index/address
string str String

A returned Struct.TableToken dataclass object has the following values:

table str Table name
row int Table row
strings Dict Strings of different types depending on which table is referenced:
- Name str Name (Method, Member, ...)
- TypeName str Type name
- TypeNamespace str Namespace name

Example:

# Import class DotNetPE from module dotnetfile
from dotnetfile import DotNetPE

# Create an instance of DotNetPE with the file path as a parameter
dotnet_file = DotNetPE('/Users/<username>/my_dotnet_assembly.exe')

# Define a (given) token we know is a string token (-> 0x70...)
token = '0x70000117'

# Get #US stream from token 0x70000117
string = dotnet_file.get_token_strings(token)

# Print out string
print(f'#US stream string from token "{token}": {string.string}')

# Get (custom) assembly attributes

get_assembly_attributes() -> Set[str]

Get all (custom) assembly attributes which provide information about an assembly.

Parameters:

Return value:

Set with attribute strings

Example:

# Import class DotNetPE from module dotnetfile
from dotnetfile import DotNetPE

# Create an instance of DotNetPE with the file path as a parameter
dotnet_file = DotNetPE('/Users/<username>/my_dotnet_assembly.exe')

# Get all assembly attributes
attributes = dotnet_file.get_assembly_attributes()

# Print out each attribute
for attribute in attributes:
    print(f'{attribute}')

# Get (custom) assembly attribute value

get_assembly_attribute_value(attribute_name: str) -> str

Get the value of a given (custom) assembly attribute.

Parameters:

attribute_name Attribute name string

Return value:

Attribute value string

Example:

# Import class DotNetPE from module dotnetfile
from dotnetfile import DotNetPE

# Create an instance of DotNetPE with the file path as a parameter
dotnet_file = DotNetPE('/Users/<username>/my_dotnet_assembly.exe')

# Get assembly GUID attribute
attribute = dotnet_file.get_assembly_attribute_value('GuidAttribute')

# Print out GUID
print(f'{attribute}')

# Get (custom) assembly attributes with their values

get_assembly_attributes_with_values() -> Dict[Optional[str], str]

Get (custom) assembly attributes with their values.

The following assembly attributes are currently searched for:

Parameters:

Return value:

The resulting dictionary has the following keys and values :

Attribute str Value name

Example:

# Import class DotNetPE from module dotnetfile
from dotnetfile import DotNetPE

# Create an instance of DotNetPE with the file path as a parameter
dotnet_file = DotNetPE('/Users/<username>/my_dotnet_assembly.exe')

# Get assembly attributes with their values
assembly_attributes_with_values = dotnet_file.get_assembly_attributes_with_values()

# Print out (found) attributes with their values
for assembly_attribute, assembly_attribute_value in assembly_attributes_with_values.items():
    if assembly_attribute_value:
        print(f'{assembly_attribute}: {assembly_attribute_value}')