100 Days of YARA: Writing Signatures for .NET Malware

However, the condition will not match the sample because the patterns suffer from common pitfalls. We will explain those pitfalls and create an improved, working signature after discussing .NET Internals. 

First detection opportunities arise in the metadata header, because obfuscators may add invalid streams, e.g., two streams with the same name, or stream names that are not defined in the specification. This anomaly alone typically does not suffice for detecting malware but can be used to craft robust obfuscator-detection signatures, which provide important information for reverse engineers and malware analysts. 

The following table denotes purposes and a high-level format description of each stream. Use this as a reference when deciding which modifiers and patterns to use in a YARA signature. 

Some streams, #Blob and #US, prepend a compressed length to each element of the stream. The compressed length is calculated as follows (see p.68 in [2]): 

As long as #US strings and #Blob entries are shorter than 128 bytes, the prepended compressed length is the same as the actual length. This is likely the case for most patterns that a malware analyst wants to create. 

It is because of the prepended length that the fullword modifier may prevent matches, if the length happens to be an alphanumeric character.

The GUID that is shown in our example screenshot is also called TypeLib ID and was first described by Brian Wallace in his article “Using .NET GUIDs to help hunt for malware”^[1]. 

The Typelib ID is added by Visual Studio and uniquely identifies a project. It is saved in the #Blob stream, therefore it is always prepended by its length 0x24, which is the same as the ‘$’ character. It is a strong pattern that can stand on its own and is also robust against recompilation.  

For malware families like AgentTesla with leaked sources, whose code or code snippets are re-used in various projects, the TypeLib ID should probably not be used if detecting the family is the goal. 

Another GUID mentioned by Wallace is the MVID in the #GUID stream. The MVID changes with recompilation and serves well in identifying a specific sample, e.g., to see if the same payload was re-packed. It does not work for writing recompilation-robust detection signatures. 

In the fixed YARA signature, we removed the “AssemblyTitle” and “Guid” strings because these are encoded in the metadata tables and do not actually appear in the binary.  

Furthermore, we use the formatting based on table 1. The $guid and $title strings are from the assembly information, so they are saved in the #Blob stream with their compressed length prepended. That means there is no need for a wide modifier. 

A common pitfall is the usage of YARA’s fullword modifier for #Blob (or #US) strings. The prepended length can be within the alphanumeric range just as it is the case with $title in our example. It has the length 0x34 which is incidentally also the character ‘a’. Therefore, the fullword modifier prevents matches for such strings, which is not what we want. 

By checking the prepended length, we have a splendid replacement for the intention of the fullword modifier. There are three different ways to check the length:  

1. It can be directly embedded into the string pattern (see $guid and $title).  

2. We can use hex patterns (not shown here), but because they are less readable, I recommend supplementing these with a comment of the decoded string.  

3. We can check the length in the condition, which is useful to have still readable wide strings (see condition for $url) 

In addition to being able to work like a fullword modifier, the inclusion of the prepended length also adds structural context for the signature pattern. An assembly info text that accidentally appears as method name (#Strings stream) is probably not the pattern we were looking for. 

To show an additional example for strings in #US and 2-byte compressed length, I also added the $url. Such a download URL might have been mentioned in an analysis report and here we assume it might be referenced by the IL code, thus part of the #US stream. The length of this url is 98 characters, which is 98*2= 96 bytes (0xC4) because the #US saves them in UTF-16. Additionally, the #US stream entries have an appended 0x0 or 0x1, which means we have to add 1 byte to the length, which is now 0xC5. The value 0xC5 is within the range of 0x80 – 0x3FFF, so 2 bytes are used to encode this length. Applying the formula, we get: (0x8000 | 0xC5) = 0x80C5. 

The buggy $timestamp did not consider that the timestamp is saved in little endian format. Knowing that this timestamp is part of the PE Header, we add this context to the pattern by placing it at a fixed offset from the PE signature. Alternatively, the “pe” module of YARA parses the timestamp – however, parsing has the drawback that it may be worse for performance and can only run on sufficiently valid PE images but may fail to detect the malware in embedded files, memory dumps or broken files. Hence, the more versatile option is the pattern-based solution. 

Finally, we change the $forms string because “WindowsFormsApp54”, “Program” and “Main” are namespace, class and method, which are placed as separate entries in the #Strings heap. Their connection is encoded in the metadata tables and cannot be covered by a single pattern. We remove “Program” and “Main” entirely from the YARA rule because they are relatively common strings. The “WindowsFormsApp54” is a default name used by Visual Studio. With exception of programming exercises, it should be uncommon among clean files and coupled with the timestamp we might find the sample that was used for the screenshot. Because “WindowsFormsApp54” is saved in #Strings, it is enclosed by zero-bytes. 

One word of caution: Specifically for threat hunting rules, which often must be written without samples, it may be error-prone to manually calculate details like the compressed length. But the knowledge about underlying structures and encodings used in the .NET streams helps to avoid typical errors as we have seen in the buggy hunt rule. When you craft actual detection signatures for production, these structural details are easily extracted and work great to avoid false positives.  

Anyone who writes signatures for x86 code knows that addresses to functions or data locations generally should be wildcarded to create robust signature patterns. That is because small changes to the code like additional variables, functions and instructions will also affect these addresses after recompilation. 

A .NET token is similar to an address in x86 in that regard. Just like addresses they might change their values with recompilation. However, they are not exactly the same and wildcarding the whole token is not recommended. 

There are two types of tokens in .NET assemblies: Coded tokens and non-coded ones. The non-coded tokens are part of the IL code.  

.NET metadata consists of a lot of tables, which define classes, parameters, methods and more. Tokens reference a row in a metadata table. That means they describe two data points: a record identifier to specify which row is used and a table index to indicate which table they reference.  

Every token consists of 4 bytes. The first byte is the table index, which is also called token type. The remaining bytes 2-4 are the record identifier(RID). While the first byte defines the metadata table, the RID defines which entry in this table is being used.  

Why is the table index also called token type? That is because every meta data table is responsible for storing entries of a certain type. For instance, methods are saved in the table mdtMethodDef, that means any token that points into this table is a method definition reference with the token type 0x06.  

The token types themselves have the same values in every .NET assembly, making them an important data point when writing signatures. The following table lists their values (see page 76 in [2]). 

The RIDs on the other hand should rather be wildcarded, because similar to addresses in x86 their values might change when table entries are added or removed, and the sample is recompiled. 

Note that we keep the integer values for the array size and the Range(0,256) call. Depending on the context and the probability that these values change, such values might need to be wildcarded too. Values that represent keys for encryption, campaign IDs or version numbers are often subject to change. 

Some articles recommend wildcarding the full token including the token type, however, there is usually no advantage in doing that. On the contrary, in addition to losing type information, this might result in bad performance if the remaining byte sequences do not have sufficient length. For YARA patterns, a minimum length of 4 consecutive bytes without wildcards is recommended because YARA’s search algorithm does a first sweep with 4-byte substrings (see [4]), which are called atoms. 

Let’s assume we want to use all that information for a YARA signature.  

Firstly, the name of a method as well as the parameter names are saved in the #Strings stream. Therefore, we know that the method name and the parameter names will be enclosed in zero-bytes and in UTF-8 format. This does not only serve us well if we need to write signatures based on screenshots alone, but also saves time if samples are available because we do not need to look up the representation of these names in a hex editor.  

Secondly, any string that is referenced by IL code is stored UTF-16 encoded in the #US heap. 

We discussed #String and #US strings already for case 1. 

Thirdly, the method’s body is the actual IL code. We discussed this part in the previous section.  

Lastly, the method signature is saved in the #Blob stream. Method signature in this context means the calling convention, parameter types and return type that the method expects and should not be confused with a detection signature. The buildup of such a method signature is as follows: 

method_sig ::= <callconven_method> <num_of_args> <return_type> [<arg_type>[,<arg_type>]*] 

Ildasm.exe shows the method signature’s byte sequence. Using the fully qualified name of a method, a suitable command to display the byte sequence is:  

ILDasm.exe /text /bytes /nobar /item="ns11.Class9::method_22" sample 

The following shows an example output with the byte sequence of the method signature in the last line: 

.method public hidebysig instance void 

          method_22(class [System.Drawing]System.Drawing.Imaging.BitmapData Param_55, 

                    class [mscorlib]System.IO.MemoryStream Param_56) cil managed 

SIG: 20 02 01 12 29 12 2D 

The method signature has the following meaning:

• 0x20 is the calling convention IMAGE_CEE_CS_CALLCONV_HASTHIS, which means this is an instance method, see [3] and p.146 in [2] 
• 0x02 is the number of arguments, which is 2 
• 0x01 is the return type VOID, see p.141 in [2] 
• 0x12 0x29 is the first argument, 0x12 refers to the CLASS type (see p.145 in [2]) and 0x29 is a coded token of the class reference 
• 0x12 0x2D is the second argument, 0x12 refers to the CLASS type (see p.145 in [2]) and 0x2D is a coded token of the class reference 

Just as we wildcard RIDs in IL code patterns, we should also wildcard the coded tokens in method signatures. Coded tokens are compressed forms of tokens to allow for smaller sizes than 4 bytes. They are not used in IL code, but in internal structures like the method signatures. 

Additionally, we prepend the length 0x07 to our pattern because it is required for every #Blob entry. 

The final hex pattern for this method signature is: 

07 20 02 01 12 ?? 12 ?? 

Method signature patterns on their own are a weak data point. Furthermore, unless the scanning engine parses .NET metadata, the method signature cannot be associated with the method body and name. So, for plain pattern search, any method with the same method signature will match. Thus, it is useful to add context to a YARA rule but will certainly not suffice on its own. 

The code references the string “X2”. Although it only consists of 2 characters, we increase the pattern of $us_string length sufficiently by using our knowledge that #US elements have a prepended length and, in this case, a trailing 0. 

Additionally, we include the class name and the namespace for this exercise. 

We extract the method signature via:  

ildasm.exe /text /bytes /nobar /item="WindowsFormsApp54.Small::Buffer" 

The byte sequence for the method signature, 0x05 0x00 0x01 0x1D 0x05 0x0E, is composed as follows:

• 0x05 is the prepended length of 5 

• 0x00 is the default calling convention, IMAGE_CEE_CS_CALLCONV_DEFAULT, see [3] and p.146 in [2] 

• 0x01 is the number of arguments 

• 0x1D means the return type is SZARRAY, see p.137 in [2] 

• 0x05 means the array's underlying type is byte, see p.134 in [2] 

• 0x0E means the first argument is of type string, see p.145 in [2]  

There is no wildcard necessary because no coded token is present.  

Knowledge about internal structures helps to add context to signatures. This results in more accurate and robust detection signatures because we increase the chances that the patterns are embedded in the correct structures.  

Furthermore, it increases our ability for expression in YARA and leads to more flexibility and less mistakes when dealing with missing information. It also increases efficiency because we do not need to look up the correct formatting in the hex editor. 

This is not only true for .NET. Other types of signatures, like those on CPython bytecode also profit from factoring in its file and data structures. 

The value of readability and maintainability should not be underestimated. Signatures that require to reverse engineer the code of the sample to determine what they detect, take often the same time for quality checks and maintenance as writing a similar signature from scratch. Yara byte patterns for IL code should always contain comments with the disassembly or decompilation of the detected IL code.

[1] Brian Wallace, 2015, “Using .NET GUIDs to help hunt for malware”, VirusBulletin 

[2] Serge Lidin, 2014, “.NET IL Assembler”, Apress 

[3] https://learn.microsoft.com/en-us/dotnet/framework/unmanaged-api/metadata/corcallingconvention-enumeration 

[4] Florian Roth, 2021, Revision 1.5, https://github.com/Neo23x0/YARA-Performance-Guidelines?tab=readme-ov-file#atoms

f9ee3eff3345ea280c01d5fce5461b24c537cf6c3dfadc626ef73eed815c2008