Debug readable obfuscation scheme

achumack · achumack · commit f40d3cce6dd7 · 2025-06-30T10:13:06.000+02:00
diff --git a/Obfuscar/Helpers/TypeReferenceExtensions.cs b/Obfuscar/Helpers/TypeReferenceExtensions.cs
@@ -68,10 +68,10 @@ public static string GetGenericName(this TypeReference type)
             for (int i = 0; i < type.GenericParameters.Count; i++)
             {
                 GenericParameter genericName = type.GenericParameters[i];
-                genericName.Name = nameMaker.UniqueName(i);
+                genericName.Name = nameMaker.UniqueName(i, null, genericName.Name);
             }
 
-            type.GetElementType().Name = nameMaker.UniqueName(type.GenericParameters.Count);
+            type.GetElementType().Name = nameMaker.UniqueName(type.GenericParameters.Count, null, type.Name);
             return type.Name;
         }
     }
diff --git a/Obfuscar/NameGroup.cs b/Obfuscar/NameGroup.cs
@@ -37,13 +37,13 @@ class NameGroup : IEnumerable<string>
 
         HashSet<string> names = new HashSet<string>();
 
-        public string GetNext()
+        public string GetNext(string originalName)
         {
             int index = _random.Next(20);
             string name;
             for (;;)
             {
-                name = NameMaker.Instance.UniqueName(index++);
+                name = NameMaker.Instance.UniqueName(index++, null, originalName);
                 if (!names.Contains(name))
                     return name;
             }
@@ -72,14 +72,14 @@ public void Remove(string name)
             names.Remove(name);
         }
 
-        public static string GetNext(IEnumerable<NameGroup> groups)
+        public static string GetNext(IEnumerable<NameGroup> groups, string originalName)
         {
             int index = 0;
 
             string name;
             for (;;)
             {
-                name = NameMaker.Instance.UniqueName(index++);
+                name = NameMaker.Instance.UniqueName(index++, null, originalName);
 
                 bool contained = false;
                 foreach (NameGroup group in groups)
diff --git a/Obfuscar/NameMaker.cs b/Obfuscar/NameMaker.cs
@@ -26,6 +26,7 @@
 
 using System;
 using System.Collections.Generic;
+using System.Linq;
 using System.Text;
 
 namespace Obfuscar
@@ -74,6 +75,9 @@ internal NameMaker()
             koreanChars = new string(chars.ToArray());
 
             UseKoreanChars = false;
+
+            // inherit global debug model obfuscation settings
+            UseDebugVersionNames = Instance?.UseDebugVersionNames ?? false; // null possible when we create first Instance
         }
 
         private void ShuffleArray<T>(IList<T> list, Random rnd)
@@ -117,16 +121,20 @@ public bool UseKoreanChars
             }
         }
 
-        public string UniqueName(int index)
-        {
-            return UniqueName(index, null);
-        }
+        /// <summary>
+        /// Try to keep it readable for debug purposes (obfuscate/rename it but keep names similar to what was before obfuscation)
+        /// </summary>
+        public bool UseDebugVersionNames { get; set; }
 
-        public string UniqueName(int index, string sep)
+        public string UniqueName(int index, string sep, string originalName)
         {
+            var postfix = string.IsNullOrEmpty(originalName) || !UseDebugVersionNames
+                ? string.Empty
+                : "_" + originalName.Split('.', '>').Last();
+
             // optimization for simple case
             if (index < numUniqueChars)
-                return uniqueChars[index].ToString();
+                return uniqueChars[index].ToString() + postfix;
 
             Stack<char> stack = new Stack<char>();
 
@@ -147,22 +155,22 @@ public string UniqueName(int index, string sep)
                 builder.Append(stack.Pop());
             }
 
-            return builder.ToString();
+            return builder.ToString() + postfix;
         }
 
-        public string UniqueNestedTypeName(int index)
+        public string UniqueNestedTypeName(int index, string originalName)
         {
-            return UniqueName(index, null);
+            return UniqueName(index, null, originalName);
         }
 
-        public string UniqueTypeName(int index)
+        public string UniqueTypeName(int index, string originalName)
         {
-            return UniqueName(index % numUniqueChars, ".");
+            return UniqueName(index % numUniqueChars, ".", originalName);
         }
 
-        public string UniqueNamespace(int index)
+        public string UniqueNamespace(int index, string originalName)
         {
-            return UniqueName(index / numUniqueChars, ".");
+            return UniqueName(index / numUniqueChars, ".", originalName);
         }
     }
 }
diff --git a/Obfuscar/Obfuscator.cs b/Obfuscar/Obfuscator.cs
@@ -252,6 +252,8 @@ private void LoadFromReader(XDocument reader, string projectFileDirectory)
                 NameMaker.Instance.UseUnicodeChars = true;
             if (Project.Settings.UseKoreanNames)
                 NameMaker.Instance.UseKoreanChars = true;
+            if (Project.Settings.UseDebugVersionNames)
+                NameMaker.Instance.UseDebugVersionNames = true;
 
             LogOutput("Loading assemblies...");
             LogOutput("Extra framework folders: ");
@@ -521,8 +523,8 @@ private void ProcessField(FieldDefinition field, TypeKey typeKey, Dictionary<str
             }
 
             var newName = Project.Settings.ReuseNames
-                ? nameGroup.GetNext()
-                : NameMaker.Instance.UniqueName(_uniqueMemberNameIndex++);
+                ? nameGroup.GetNext(field.Name)
+                : NameMaker.Instance.UniqueName(_uniqueMemberNameIndex++, null, field.Name);
 
             RenameField(info, fieldKey, field, newName);
             nameGroup.Add(newName);
@@ -582,7 +584,7 @@ public void RenameParams()
 
                     int index = 0;
                     foreach (GenericParameter param in type.GenericParameters)
-                        param.Name = NameMaker.Instance.UniqueName(index++);
+                        param.Name = NameMaker.Instance.UniqueName(index++, null, param.Name);
                 }
             }
         }
@@ -601,7 +603,7 @@ private void RenameParams(MethodDefinition method, AssemblyInfo info)
             int index = 0;
             foreach (GenericParameter param in method.GenericParameters)
                 if (param.CustomAttributes.Count == 0)
-                    param.Name = NameMaker.Instance.UniqueName(index++);
+                    param.Name = NameMaker.Instance.UniqueName(index++, null, param.Name);
         }
 
         /// <summary>
@@ -689,19 +691,19 @@ public void RenameTypes(HashSet<string> namesInXaml)
                     if (type.IsNested)
                     {
                         ns = "";
-                        name = NameMaker.Instance.UniqueNestedTypeName(type.DeclaringType.NestedTypes.IndexOf(type));
+                        name = NameMaker.Instance.UniqueNestedTypeName(type.DeclaringType.NestedTypes.IndexOf(type), type.Name);
                     }
                     else
                     {
                         if (Project.Settings.ReuseNames)
                         {
-                            name = NameMaker.Instance.UniqueTypeName(typeIndex);
-                            ns = NameMaker.Instance.UniqueNamespace(typeIndex);
+                            name = NameMaker.Instance.UniqueTypeName(typeIndex, type.Name);
+                            ns = NameMaker.Instance.UniqueNamespace(typeIndex, type.Name);
                         }
                         else
                         {
-                            name = NameMaker.Instance.UniqueName(_uniqueTypeNameIndex);
-                            ns = NameMaker.Instance.UniqueNamespace(_uniqueTypeNameIndex);
+                            name = NameMaker.Instance.UniqueName(_uniqueTypeNameIndex, null, type.Name);
+                            ns = NameMaker.Instance.UniqueNamespace(_uniqueTypeNameIndex, type.Name);
                             _uniqueTypeNameIndex++;
                         }
                     }
@@ -1002,7 +1004,8 @@ private int ProcessProperty(TypeKey typeKey, PropertyDefinition prop, AssemblyIn
             else if (prop.CustomAttributes.Count > 0)
             {
                 // If a property has custom attributes we don't remove the property but rename it instead.
-                var newName = NameMaker.Instance.UniqueName(Project.Settings.ReuseNames ? index++ : _uniqueMemberNameIndex++);
+                var newName = NameMaker.Instance.UniqueName(Project.Settings.ReuseNames ? index++ : _uniqueMemberNameIndex++,
+                    null, prop.Name);
                 RenameProperty(info, propKey, prop, newName);
             }
             else
@@ -1301,7 +1304,7 @@ private void RenameVirtualMethod(Dictionary<TypeKey, Dictionary<ParamSig, NameGr
                     NameGroup[] nameGroups = GetNameGroups(baseSigNames, @group.Methods, sig);
 
                     // for an internal group, get next unused name
-                    groupName = NameGroup.GetNext(nameGroups);
+                    groupName = NameGroup.GetNext(nameGroups, method.Name);
                     @group.Name = groupName;
 
                     // set up methods to be renamed
@@ -1415,7 +1418,7 @@ private string GetNewName(Dictionary<ParamSig, NameGroup> sigNames, MethodDefini
 
             NameGroup nameGroup = GetNameGroup(sigNames, sig);
 
-            string newName = nameGroup.GetNext();
+            string newName = nameGroup.GetNext(method.Name);
 
             // make sure the name groups is updated
             nameGroup.Add(newName);
@@ -1821,7 +1824,7 @@ public void ProcessStrings(MethodDefinition method,
                         MethodDefinition individualStringMethodDefinition;
                         if (!_methodByString.TryGetValue(str, out individualStringMethodDefinition))
                         {
-                            string methodName = NameMaker.Instance.UniqueName(_nameIndex++);
+                            string methodName = NameMaker.Instance.UniqueName(_nameIndex++, null, "StringReplacedWithCall");
 
                             // Add the string to the data array
                             byte[] stringBytes = Encoding.UTF8.GetBytes(str);
diff --git a/Obfuscar/Settings.cs b/Obfuscar/Settings.cs
@@ -46,6 +46,7 @@ public Settings(Variables vars)
             ReuseNames = XmlConvert.ToBoolean(vars.GetValue("ReuseNames", "true"));
             UseUnicodeNames = XmlConvert.ToBoolean(vars.GetValue("UseUnicodeNames", "false"));
             UseKoreanNames = XmlConvert.ToBoolean(vars.GetValue("UseKoreanNames", "false"));
+            UseDebugVersionNames = XmlConvert.ToBoolean(vars.GetValue("UseDebugVersionNames", "false"));
             HideStrings = XmlConvert.ToBoolean(vars.GetValue("HideStrings", "true"));
             Optimize = XmlConvert.ToBoolean(vars.GetValue("OptimizeMethods", "true"));
             SuppressIldasm = XmlConvert.ToBoolean(vars.GetValue("SuppressIldasm", "true"));
@@ -98,6 +99,11 @@ public Settings(Variables vars)
 
         public bool UseKoreanNames { get; }
 
+        /// <summary>
+        /// Try to keep it readable for debug purposes (obfuscate/rename it but keep names similar to what was before obfuscation)
+        /// </summary>
+        public bool UseDebugVersionNames { get; }
+
         public bool AbortOnInconsistentState { get; }
 
         public bool LogRecoveredInconsistentState { get; }

Original file line number	Diff line number	Diff line change
`@@ -68,10 +68,10 @@ public static string GetGenericName(this TypeReference type)`
`68`	`68`	`for (int i = 0; i < type.GenericParameters.Count; i++)`
`69`	`69`	`{`
`70`	`70`	`GenericParameter genericName = type.GenericParameters[i];`
`71`		`- genericName.Name = nameMaker.UniqueName(i);`
	`71`	`+ genericName.Name = nameMaker.UniqueName(i, null, genericName.Name);`
`72`	`72`	`}`
`73`	`73`
`74`		`- type.GetElementType().Name = nameMaker.UniqueName(type.GenericParameters.Count);`
	`74`	`+ type.GetElementType().Name = nameMaker.UniqueName(type.GenericParameters.Count, null, type.Name);`
`75`	`75`	`return type.Name;`
`76`	`76`	`}`
`77`	`77`	`}`
Original file line number	Diff line number	Diff line change
`@@ -37,13 +37,13 @@ class NameGroup : IEnumerable<string>`
`37`	`37`
`38`	`38`	`HashSet<string> names = new HashSet<string>();`
`39`	`39`
`40`		`- public string GetNext()`
	`40`	`+ public string GetNext(string originalName)`
`41`	`41`	`{`
`42`	`42`	`int index = _random.Next(20);`
`43`	`43`	`string name;`
`44`	`44`	`for (;;)`
`45`	`45`	`{`
`46`		`- name = NameMaker.Instance.UniqueName(index++);`
	`46`	`+ name = NameMaker.Instance.UniqueName(index++, null, originalName);`
`47`	`47`	`if (!names.Contains(name))`
`48`	`48`	`return name;`
`49`	`49`	`}`
`@@ -72,14 +72,14 @@ public void Remove(string name)`
`72`	`72`	`names.Remove(name);`
`73`	`73`	`}`
`74`	`74`
`75`		`- public static string GetNext(IEnumerable<NameGroup> groups)`
	`75`	`+ public static string GetNext(IEnumerable<NameGroup> groups, string originalName)`
`76`	`76`	`{`
`77`	`77`	`int index = 0;`
`78`	`78`
`79`	`79`	`string name;`
`80`	`80`	`for (;;)`
`81`	`81`	`{`
`82`		`- name = NameMaker.Instance.UniqueName(index++);`
	`82`	`+ name = NameMaker.Instance.UniqueName(index++, null, originalName);`
`83`	`83`
`84`	`84`	`bool contained = false;`
`85`	`85`	`foreach (NameGroup group in groups)`
Original file line number	Diff line number	Diff line change
`@@ -26,6 +26,7 @@`
`26`	`26`
`27`	`27`	`using System;`
`28`	`28`	`using System.Collections.Generic;`
	`29`	`+using System.Linq;`
`29`	`30`	`using System.Text;`
`30`	`31`
`31`	`32`	`namespace Obfuscar`
`@@ -74,6 +75,9 @@ internal NameMaker()`
`74`	`75`	`koreanChars = new string(chars.ToArray());`
`75`	`76`
`76`	`77`	`UseKoreanChars = false;`
	`78`	`+`
	`79`	`+ // inherit global debug model obfuscation settings`
	`80`	`+ UseDebugVersionNames = Instance?.UseDebugVersionNames ?? false; // null possible when we create first Instance`
`77`	`81`	`}`
`78`	`82`
`79`	`83`	`private void ShuffleArray<T>(IList<T> list, Random rnd)`
`@@ -117,16 +121,20 @@ public bool UseKoreanChars`
`117`	`121`	`}`
`118`	`122`	`}`
`119`	`123`
`120`		`- public string UniqueName(int index)`
`121`		`- {`
`122`		`- return UniqueName(index, null);`
`123`		`- }`
	`124`	`+ /// <summary>`
	`125`	`+ /// Try to keep it readable for debug purposes (obfuscate/rename it but keep names similar to what was before obfuscation)`
	`126`	`+ /// </summary>`
	`127`	`+ public bool UseDebugVersionNames { get; set; }`
`124`	`128`
`125`		`- public string UniqueName(int index, string sep)`
	`129`	`+ public string UniqueName(int index, string sep, string originalName)`
`126`	`130`	`{`
	`131`	`+ var postfix = string.IsNullOrEmpty(originalName) \|\| !UseDebugVersionNames`
	`132`	`+ ? string.Empty`
	`133`	`+ : "_" + originalName.Split('.', '>').Last();`
	`134`	`+`
`127`	`135`	`// optimization for simple case`
`128`	`136`	`if (index < numUniqueChars)`
`129`		`- return uniqueChars[index].ToString();`
	`137`	`+ return uniqueChars[index].ToString() + postfix;`
`130`	`138`
`131`	`139`	`Stack<char> stack = new Stack<char>();`
`132`	`140`
`@@ -147,22 +155,22 @@ public string UniqueName(int index, string sep)`
`147`	`155`	`builder.Append(stack.Pop());`
`148`	`156`	`}`
`149`	`157`
`150`		`- return builder.ToString();`
	`158`	`+ return builder.ToString() + postfix;`
`151`	`159`	`}`
`152`	`160`
`153`		`- public string UniqueNestedTypeName(int index)`
	`161`	`+ public string UniqueNestedTypeName(int index, string originalName)`
`154`	`162`	`{`
`155`		`- return UniqueName(index, null);`
	`163`	`+ return UniqueName(index, null, originalName);`
`156`	`164`	`}`
`157`	`165`
`158`		`- public string UniqueTypeName(int index)`
	`166`	`+ public string UniqueTypeName(int index, string originalName)`
`159`	`167`	`{`
`160`		`- return UniqueName(index % numUniqueChars, ".");`
	`168`	`+ return UniqueName(index % numUniqueChars, ".", originalName);`
`161`	`169`	`}`
`162`	`170`
`163`		`- public string UniqueNamespace(int index)`
	`171`	`+ public string UniqueNamespace(int index, string originalName)`
`164`	`172`	`{`
`165`		`- return UniqueName(index / numUniqueChars, ".");`
	`173`	`+ return UniqueName(index / numUniqueChars, ".", originalName);`
`166`	`174`	`}`
`167`	`175`	`}`
`168`	`176`	`}`
Original file line number	Diff line number	Diff line change
`@@ -252,6 +252,8 @@ private void LoadFromReader(XDocument reader, string projectFileDirectory)`
`252`	`252`	`NameMaker.Instance.UseUnicodeChars = true;`
`253`	`253`	`if (Project.Settings.UseKoreanNames)`
`254`	`254`	`NameMaker.Instance.UseKoreanChars = true;`
	`255`	`+ if (Project.Settings.UseDebugVersionNames)`
	`256`	`+ NameMaker.Instance.UseDebugVersionNames = true;`
`255`	`257`
`256`	`258`	`LogOutput("Loading assemblies...");`
`257`	`259`	`LogOutput("Extra framework folders: ");`
`@@ -521,8 +523,8 @@ private void ProcessField(FieldDefinition field, TypeKey typeKey, Dictionary<str`
`521`	`523`	`}`
`522`	`524`
`523`	`525`	`var newName = Project.Settings.ReuseNames`
`524`		`- ? nameGroup.GetNext()`
`525`		`- : NameMaker.Instance.UniqueName(_uniqueMemberNameIndex++);`
	`526`	`+ ? nameGroup.GetNext(field.Name)`
	`527`	`+ : NameMaker.Instance.UniqueName(_uniqueMemberNameIndex++, null, field.Name);`
`526`	`528`
`527`	`529`	`RenameField(info, fieldKey, field, newName);`
`528`	`530`	`nameGroup.Add(newName);`
`@@ -582,7 +584,7 @@ public void RenameParams()`
`582`	`584`
`583`	`585`	`int index = 0;`
`584`	`586`	`foreach (GenericParameter param in type.GenericParameters)`
`585`		`- param.Name = NameMaker.Instance.UniqueName(index++);`
	`587`	`+ param.Name = NameMaker.Instance.UniqueName(index++, null, param.Name);`
`586`	`588`	`}`
`587`	`589`	`}`
`588`	`590`	`}`
`@@ -601,7 +603,7 @@ private void RenameParams(MethodDefinition method, AssemblyInfo info)`
`601`	`603`	`int index = 0;`
`602`	`604`	`foreach (GenericParameter param in method.GenericParameters)`
`603`	`605`	`if (param.CustomAttributes.Count == 0)`
`604`		`- param.Name = NameMaker.Instance.UniqueName(index++);`
	`606`	`+ param.Name = NameMaker.Instance.UniqueName(index++, null, param.Name);`
`605`	`607`	`}`
`606`	`608`
`607`	`609`	`/// <summary>`
`@@ -689,19 +691,19 @@ public void RenameTypes(HashSet<string> namesInXaml)`
`689`	`691`	`if (type.IsNested)`
`690`	`692`	`{`
`691`	`693`	`ns = "";`
`692`		`- name = NameMaker.Instance.UniqueNestedTypeName(type.DeclaringType.NestedTypes.IndexOf(type));`
	`694`	`+ name = NameMaker.Instance.UniqueNestedTypeName(type.DeclaringType.NestedTypes.IndexOf(type), type.Name);`
`693`	`695`	`}`
`694`	`696`	`else`
`695`	`697`	`{`
`696`	`698`	`if (Project.Settings.ReuseNames)`
`697`	`699`	`{`
`698`		`- name = NameMaker.Instance.UniqueTypeName(typeIndex);`
`699`		`- ns = NameMaker.Instance.UniqueNamespace(typeIndex);`
	`700`	`+ name = NameMaker.Instance.UniqueTypeName(typeIndex, type.Name);`
	`701`	`+ ns = NameMaker.Instance.UniqueNamespace(typeIndex, type.Name);`
`700`	`702`	`}`
`701`	`703`	`else`
`702`	`704`	`{`
`703`		`- name = NameMaker.Instance.UniqueName(_uniqueTypeNameIndex);`
`704`		`- ns = NameMaker.Instance.UniqueNamespace(_uniqueTypeNameIndex);`
	`705`	`+ name = NameMaker.Instance.UniqueName(_uniqueTypeNameIndex, null, type.Name);`
	`706`	`+ ns = NameMaker.Instance.UniqueNamespace(_uniqueTypeNameIndex, type.Name);`
`705`	`707`	`_uniqueTypeNameIndex++;`
`706`	`708`	`}`
`707`	`709`	`}`
`@@ -1002,7 +1004,8 @@ private int ProcessProperty(TypeKey typeKey, PropertyDefinition prop, AssemblyIn`
`1002`	`1004`	`else if (prop.CustomAttributes.Count > 0)`
`1003`	`1005`	`{`
`1004`	`1006`	`// If a property has custom attributes we don't remove the property but rename it instead.`
`1005`		`- var newName = NameMaker.Instance.UniqueName(Project.Settings.ReuseNames ? index++ : _uniqueMemberNameIndex++);`
	`1007`	`+ var newName = NameMaker.Instance.UniqueName(Project.Settings.ReuseNames ? index++ : _uniqueMemberNameIndex++,`
	`1008`	`+ null, prop.Name);`
`1006`	`1009`	`RenameProperty(info, propKey, prop, newName);`
`1007`	`1010`	`}`
`1008`	`1011`	`else`
`@@ -1301,7 +1304,7 @@ private void RenameVirtualMethod(Dictionary<TypeKey, Dictionary<ParamSig, NameGr`
`1301`	`1304`	`NameGroup[] nameGroups = GetNameGroups(baseSigNames, @group.Methods, sig);`
`1302`	`1305`
`1303`	`1306`	`// for an internal group, get next unused name`
`1304`		`- groupName = NameGroup.GetNext(nameGroups);`
	`1307`	`+ groupName = NameGroup.GetNext(nameGroups, method.Name);`
`1305`	`1308`	`@group.Name = groupName;`
`1306`	`1309`
`1307`	`1310`	`// set up methods to be renamed`
`@@ -1415,7 +1418,7 @@ private string GetNewName(Dictionary<ParamSig, NameGroup> sigNames, MethodDefini`
`1415`	`1418`
`1416`	`1419`	`NameGroup nameGroup = GetNameGroup(sigNames, sig);`
`1417`	`1420`
`1418`		`- string newName = nameGroup.GetNext();`
	`1421`	`+ string newName = nameGroup.GetNext(method.Name);`
`1419`	`1422`
`1420`	`1423`	`// make sure the name groups is updated`
`1421`	`1424`	`nameGroup.Add(newName);`
`@@ -1821,7 +1824,7 @@ public void ProcessStrings(MethodDefinition method,`
`1821`	`1824`	`MethodDefinition individualStringMethodDefinition;`
`1822`	`1825`	`if (!_methodByString.TryGetValue(str, out individualStringMethodDefinition))`
`1823`	`1826`	`{`
`1824`		`- string methodName = NameMaker.Instance.UniqueName(_nameIndex++);`
	`1827`	`+ string methodName = NameMaker.Instance.UniqueName(_nameIndex++, null, "StringReplacedWithCall");`
`1825`	`1828`
`1826`	`1829`	`// Add the string to the data array`
`1827`	`1830`	`byte[] stringBytes = Encoding.UTF8.GetBytes(str);`