Code stripping/obfuscation, a comprehensive how-to

[Kelly]

This lecture is technical and not for everyone. If you are not a coder already, you might as well skip it since it won't likely make much sense. If you are a coder and you are interested in how protection is done then enjoy!

First off I messaged Heston and got permission to write this small lecture. Knowing this would contain sensitive information I wanted to be sure he was OK with me doing it. Since he's been gracious enough to give me mod rights on the forum I don't have to worry about being censored or having my posts edited. As a thank you I've been posting some source codes and now I'm going to move into more technical territory that's usually not discussed openly: how to write and compile your code so that it cannot be used by someone else.

First off let's discuss some theory so the further lessons make sense. Let's take the example of a simple sniper rifle mod. That .u file contains a single class called "MyUberRifle" that extends SniperRifle (a stock class). If you look at that .u file with a program like WOTGreal or UTPT you will see source code. If you summon the rifle in a game you can see the changes made. All seems good. It's a normal mod like everything else you are used to using.

So what's really going on under the hood? Well I want you to think of the .u file as a box. Inside that box is the sniper rifle. Sounds good so far? Well, here's the part most people don't get...If you look on the outside of that box you will see an envelope stuck to the side. Inside that envelope is the code that you are seeing with WOTGreal/UTPT. The code and the rifle are two different things. This is super important to understand. Everything from here on will depend on you knowing this.

Now I know you are probably thinking "Well, what's in the box?"

0373.jpg (18.71 KiB) Viewed 10054 times

When you 'compiled' your mod and made the .u file the compiler (that's the UCC you see in your system folder) converted your script code into machine code but saved a copy of that code and stuck it on the side of the box for you to reference. That's why you can take a hex editor and poke into the .u file and see the changes your script created. In essence the .u file contains 2 copies of your mod work, one in normal script form (for reference) and one in machine code (the engine actually uses this one).

With very few exceptions we cannot make changes to the machine code (more on that in another tutorial) but we can do all kinds of stuff to the code that is saved on the side of the box. It can be discarded and the mod is considered "Stripped" or you can make it so the code is very, very difficult to interpret and then it's considered "Obfuscated". There are positives and negatives to either choice and so you'll have to decide which way best suits what you want to do.

So now you understand the basics of what a .u file contains let's get on with the task at hand and I'll teach you how to protect your work.

[Kelly]

Before I get into the how part, let's compare the costs/benefits of these two protections:

Stripping
pro: fast, easy to do, no extra coding knowledge needed, provides some protection against your code being read, stripped variables still replicate
con: source code can be recovered using UTPT and patience, variables are not hidden

Obfuscating
pro: excellent level of code protection, variables are completely hidden from code readers
con: requires code to be specially written for obfuscating, can be confusing at first, requires an external program to scramble the source code, hidden variables will not replicate properly

As you can see stripping is way easier but doesn't offer anywhere near the protection of obfuscation. The main issue with obfuscation is that it requires a good bit of extra knowledge and that once you obfuscate a variable it won't properly replicate out to external mods on the server. Let me explain this a bit further. Let's say you have a mod you have obfuscated that tracks cheating players (like my CAC mod posted in the source code section). One of the string variables in the mod is the players name. Internally I can use that variable within the CAC mod and it will work BUT if I try to replicate that variable out of CAC and send it to another place (like the scoreboard) then it will likely fail because that variable is obfuscated. Consider obfuscated mods as 'sandboxes' and that the things you do while inside them will need to remain there. I have more to say on that but I'll save it for that part of the lecture. I hope all this isn't too confusing, it takes a bit to wrap yourself around the concepts.

Here's a simple graphic to show you what code looks like once it's gone through each method


At first glance you'd think stripping is superior. The code is totally gone, right? Has to be better. Well the main issue with simple strips is that you can recover the code using UTPT since it's only been erased and not scrambled. However, this is mostly enough protection so that people will leave your work alone. General mod work, weapons, etc all would be good candidates for this method of protection. It's not until you get into anticheat level modding that you need the full protection of obfuscating. I've seen a lot of stripped mods floating around and by the time you develop the skill level to bypass this type of protection you almost always have learned all about rights and ownership and you willingly respect the fact that the author attempted to protect his work.

Now that you have a good basic understanding of the ideals let's get our hands dirty and strip some code...

[Kelly]

Stripping your mod

It's not at all hard to strip code. You don't even need the source code to do it. You just need good old Unreal editor and your target mod. Here are the steps in order (do not skip, do not change the sequence). For this exercise I will be stripping the mod "goCounter".

1. Open a fresh instance of Ued. This is important, you don't want ANYTHING in the resident memory of the editor. Please don't skip this or open a map and then try to strip. Close out everything Unreal and then open a fresh editor.
2. In the actor browser select File and then open your target mod.
3. Expand the actor tree and find all the classes of the target mod you want to strip. You can strip a single class or all of them, doesn't matter.

gc1.jpg (111.71 KiB) Viewed 10056 times

4. Each class that you want to strip you need to right-click and choose "Edit Script". This will open the uscript browser. The classes that you want stripped will be listed down the left hand pane.
5. This is important! When you have selected all your classes you will need to then select one more random class. For some odd reason the last selected class you strip is often not done so you need to pick one last random one. Remember this random one and be sure it's done last. You won't actually strip this class so don't worry and just grab whatever is there. I usually pick " ZoneInfo" since it will remain on the bottom of the pane and out of my way as I strip.
6. Now go back to the top of the list of classes you want to strip and select the first one. See all the code in the right pane? Select it all (CTRL+A) and then hit space. This will remove all the script. Now type in "This code is stripped" if you want or leave it blank.

gc2.jpg (200.4 KiB) Viewed 10056 times

gc3.jpg (42.66 KiB) Viewed 10056 times

7. Go down the list of classes and repeat the script blanking. Be sure to do your random extra one last.
8. When you have done them all you can close the uscript browser and go back to the actor browser. Make sure View>Show Packages is active and tick the box next to the mod you are stripping and ONLY that box!!!
9. Select File>Save Selected Packages

gc4.jpg (101.03 KiB) Viewed 10056 times

10. Drink beer because you are now a filthy code stripper. Oh, and restart Ued so it can clear it's buffers.

You can see now that your random class you stripped last won't be saved since you didn't tick any other boxes so it doesn't matter what you use for that. If you use WOTGreal to look at your stripped mod you'll see the code is now gone and if you put the message "This code is stripped" then that's all you'll see. If you are extra evil you can strip the code and replace it with malfunctioning code and drive people crazy that try to recover your mod (heh heh heh). I'm not saying I've done this but I...um...know a guy....

I keep a safe copy of the unstripped mod as well as the source code put up just in case. You should do that too. You don't want to end up having a stripped mod as your only copy of the work. Believe me, it happens. Safe copies will save your life once you start messing with these protections.

[Kelly]

Obfuscating your mod

This will require a fairly comprehensive lecture so it may not be for every hobbyist UT coder. I'll walk you through how to write your code for the obfuscator, what's being done, and what the results will be. At the end of the lecture I'll post the actual obfuscator as a download.

First off, you won't need to do this as a two-step process. The obfuscator has a built-in code stripper and both protections can be done at the same time using the tool. Doing both makes your code very secure and only the very best coders could reconstruct your mod. Even then it would be VERY hard to do and would still be imperfect. Proper obfuscation pretty much ensures your mod will remain yours provided you do it correctly. This does NOT mean it's perfectly safe and secure though. Even a properly protected mod can be explored with a hex editor (more on that in a further lecture) and certain values could be hex edited to bypass for instance. This is how you get around anticheats if you are wanting to exploit the server. The very nature of an open-source, moddable engine like Unreal provides this to be necessary. It's give-and-take, the ease of which you can mod changes in your server also makes it so that those changes have to be seen by the clients and therefore they usually get the ability to see the way those changes are made. That doesn't mean life is easy for them though, and I aim to make it as hard as possible

What's actually going on when you obfuscate? I'm going to shorten it to "Obb'ing" from here on so it's easier to type. When you Ob a mod you are making certain parts of the script be written over with gibberish that code readers will not be able to handle. When stripping a mod you only remove the code. This means a good decompiler like UTPT can often recover the code by looking at the machine code and rebuilding the source. By obbing the source you make it so decompilers don't know which variables are garbage and which are real. The end result is code that looks like the lower right box a few posts above, the code is just...missing. You can't tell even the variable or function name let alone what it was doing.

Let's set some important ground rules for obbing. These are quite important so don't neglect this part just to get to the end of the lecture. First off when you obb a variable or function it cannot be already existing. This is because obbing also prevents replication in most cases. Your obbed variable will persist WITHIN the mod but will not go out to other mods correctly. This means you will need to write your own functions so they can be obbed but it also does not prevent you from hiding default functions. You just simply call them from a new function you create which CAN be obbed. Want an example? OK, take for example this bit of code from GameInfo:

Code: Select all

// Set gameplay speed.
function SetGameSpeed( Float T )
{
    GameSpeed = FMax(T, 0.1);
    Level.TimeDilation = GameSpeed;
    SetTimer(Level.TimeDilation, true);
}

Since I can't strip the function because it's a default one I just create a new one that will do the same thing:

Code: Select all

function MyNewGameSpeed( Float T )
{
    GameSpeed = FMax(T, 0.1);
    Level.TimeDilation = GameSpeed;
    SetTimer(Level.TimeDilation, true);
}

Since this is a new function that does not exist anywhere else I can obb this completely. I know what you are thinking too..."Isn't Game Speed a replicated value?" Why, yes it is BUT this code would be used to control a server's game speed so it will adjust that speed. Once the game speed is adjusted THEN the value will replicate out to the client in the normal way it always does, through GameInfo class in the default engine code. This lets us pass the new game speed setting from obbed code to client in a round-about way. Are we good so far?

[Kelly]

So now you understand the ground rules, let's learn to code so that the program can properly obb your mod. I find it best to code my mod completely THEN go back and add the identifiers to it. Let's take a simple mod class to work on. In my private anticheat I made a class that checks for players to see if they are using the multigun exploit (exists in MonsterHunt mostly) and it will either kill them for doing it or silently log the use of the exploit to the server so the admin will know. Here is the source code for that class. (BTW "Small3WoodFragments" is a logging class, I was trying to make it difficult to understand):

Code: Select all

class NoMultigun expands Mutator config(CAC);

var private Small3WoodFragments AT3Log;
var config bool LogOnly;

function PostBeginPlay()
{
	SetTimer(5, True);
	AT3Log = spawn(class'Small3WoodFragments');
	log("*    CombinedAC: MultiGun is Active                  *");
}

function Timer()
{
	local Pawn P;
	local string tweakstr;

	for (P = Level.PawnList; P != None; P = P.nextPawn)
	{
		if (PlayerPawn(P) != None && !P.bHidden && P.Health > 0 && P.PlayerReplicationInfo != None
		&& P.PlayerReplicationInfo.bFeigningDeath && (P.bFire != 0 || P.bAltFire != 0))
		{
			tweakstr = ("*MultiGunUse* " $ P.PlayerReplicationInfo.PlayerName $ " attempted to use multigun cheat.");
			ATLogThis(tweakstr, level.game.gameReplicationInfo.serverName);
			log("---------------- MultiGun Detected ----------------", 'MultiGun_Detect');
			log(P.PlayerReplicationInfo.PlayerName $ " tried to multigun and was punished by the server.", 'MultiGun_Detect');
			log("---------------------------------------------------", 'MultiGun_Detect');
			
			if(!LogOnly)
			{
				BroadcastMessage(P.PlayerReplicationInfo.PlayerName $ " attempted to multigun and was punished!", false, '');
				P.ClientMessage("Multigunning is NOT allowed in this server", 'CriticalEvent', True);
				P.TakeDamage(500000, None, P.Location - (P.CollisionHeight*vect(0,0,1)), vect(0,0,200000), 'MultiGunDmg');
			}
		}
	}
}

function ATLogThis(string str, string serverName)
{
   local string parts[];

   AT3Log.StartLog();
   AT3Log.logEventString("Server Name: " $ serverName);
   AT3Log.logEventString(str);
   AT3Log.stopLog();
}

defaultproperties
{
	LogOnly=False
}

Because I don't want the player to easily see what I'm doing I want to obfuscate this class. You can obfuscate two things: variables and functions. To obfuscate them you need to add "xx" to the beginning of functions and "zz" to the beginning of variables you want obfuscated. I cannot stress enough that you MUST be careful and edit EVERY instance of your function/variable correctly. It's time consuming for sure but the results are simply amazing.

Here is the code properly edited to be ready for obfuscation:

Code: Select all

class NoMultigun expands Mutator config(CAC);

var private Small3WoodFragments zzAT3Log;
var config bool LogOnly;

function PostBeginPlay()
{
	SetTimer(5, True);
	zzAT3Log = spawn(class'Small3WoodFragments');
	log("*    CombinedAC: MultiGun is Active                  *");
}

function Timer()
{
	local Pawn zzP;
	local string zztweakstr;

	for (zzP = Level.PawnList; zzP != None; zzP = zzP.nextPawn)
	{
		if (PlayerPawn(zzP) != None && !zzP.bHidden && zzP.Health > 0 && zzP.PlayerReplicationInfo != None 
		&& zzP.PlayerReplicationInfo.bFeigningDeath && (zzP.bFire != 0 || zzP.bAltFire != 0))
		{
			zztweakstr = ("*MultiGunUse* " $ zzP.PlayerReplicationInfo.PlayerName $ " attempted to use multigun cheat.");
			xxATLogThis(zztweakstr, level.game.gameReplicationInfo.serverName);
			log("---------------- MultiGun Detected ----------------", 'MultiGun_Detect');
			log(zzP.PlayerReplicationInfo.PlayerName $ " tried to multigun and was punished by the server.", 'MultiGun_Detect');
			log("---------------------------------------------------", 'MultiGun_Detect');
			
			if(!LogOnly)
			{
				BroadcastMessage(zzP.PlayerReplicationInfo.PlayerName $ " attempted to multigun and was punished!", false, '');
				zzP.ClientMessage("Multigunning is NOT allowed in this server", 'CriticalEvent', True);
				zzP.TakeDamage(500000, None, zzP.Location - (zzP.CollisionHeight*vect(0,0,1)), vect(0,0,200000), 'MultiGunDmg');
			}
		}
	}
}

function xxATLogThis(string str, string serverName)
{
   local string parts[];

   zzAT3Log.StartLog();
   zzAT3Log.logEventString("Server Name: " $ serverName);
   zzAT3Log.logEventString(str);
   zzAT3Log.stopLog();
}

defaultproperties
{
	LogOnly=False
}

If you compare the two classes you will see how to edit your code so it works with the obfuscator. Once obbed this is how the code for timer will look in WOTGreal:

Code: Select all

function Timer ()
{
	local private Pawn ;
	local private string ;

	 = Level.PawnList;
	if ( UnknownFunction119(,None) )
	{
		if ( UnknownFunction130(UnknownFunction130(UnknownFunction130(UnknownFunction130(UnknownFunction130(UnknownFunction119(PlayerPawn(),None),UnknownFunction129(.bHidden)),UnknownFunction151(.Health,0)),UnknownFunction119(.PlayerReplicationInfo,None)),.PlayerReplicationInfo.bFeigningDeath),UnknownFunction132(UnknownFunction155(.bFire,0),UnknownFunction155(.bAltFire,0))) )
		{
			 = UnknownFunction112(UnknownFunction112("*MultiGunUse* ",.PlayerReplicationInfo.PlayerName)," attempted to use multigun cheat.");
			(,Level.Game.GameReplicationInfo.ServerName);
			UnknownFunction231("---------------- MultiGun Detected ----------------",'MultiGun_Detect');
			UnknownFunction231(UnknownFunction112(.PlayerReplicationInfo.PlayerName," tried to multigun and was punished by the server."),'MultiGun_Detect');
			UnknownFunction231("---------------------------------------------------",'MultiGun_Detect');
			if ( UnknownFunction129(LogOnly) )
			{
				BroadcastMessage(UnknownFunction112(.PlayerReplicationInfo.PlayerName," attempted to multigun and was punished!"),False,'None');
				.ClientMessage("Multigunning is NOT allowed in this server",'CriticalEvent',True);
				.TakeDamage(500000,None,UnknownFunction216(.Location,UnknownFunction213(.CollisionHeight,vect(0.00,0.00,1.00))),vect(0.00,0.00,200000.00),'MultiGunDmg');
			}
		}
		 = .nextPawn;
		goto JL0014;
	}
}

UTPT decompiles it slightly better but it's still WAY off:

Code: Select all

function Timer ()
{
	local private Pawn ;
	local private string ;

	 = Level.PawnList;
	if ( UnknownFunction119(,None) )
	{
		if ( UnknownFunction130(UnknownFunction130(UnknownFunction130(UnknownFunction130(UnknownFunction130(UnknownFunction119(PlayerPawn(),None),UnknownFunction129(.bHidden)),UnknownFunction151(.Health,0)),UnknownFunction119(.PlayerReplicationInfo,None)),.PlayerReplicationInfo.bFeigningDeath),UnknownFunction132(UnknownFunction155(.bFire,0),UnknownFunction155(.bAltFire,0))) )
		{
			 = UnknownFunction112(UnknownFunction112("*MultiGunUse* ",.PlayerReplicationInfo.PlayerName)," attempted to use multigun cheat.");
			(,Level.Game.GameReplicationInfo.ServerName);
			UnknownFunction231("---------------- MultiGun Detected ----------------",'MultiGun_Detect');
			UnknownFunction231(UnknownFunction112(.PlayerReplicationInfo.PlayerName," tried to multigun and was punished by the server."),'MultiGun_Detect');
			UnknownFunction231("---------------------------------------------------",'MultiGun_Detect');
			if ( UnknownFunction129(LogOnly) )
			{
				BroadcastMessage(UnknownFunction112(.PlayerReplicationInfo.PlayerName," attempted to multigun and was punished!"),False,'None');
				.ClientMessage("Multigunning is NOT allowed in this server",'CriticalEvent',True);
				.TakeDamage(500000,None,UnknownFunction216(.Location,UnknownFunction213(.CollisionHeight,vect(0.00,0.00,1.00))),vect(0.00,0.00,200000.00),'MultiGunDmg');
			}
		}
		 = .nextPawn;
		goto JL0014;
	}
}

[Kelly]

I could have made it even more obscured by calling timer from a new function controlled by tick and totally hidden everything but I just didn't need to go all out for this. Obscuring the variables is enough to protect it from being easily bypassed/decompiled. Had I been making this anticheat for more broad use I would have done this.

So there you have it. You know which variables/functions to obb and how to code so the program knows which ones to do. Now let's talk about the program itself and how to use it. Since the program is an exe you'll need to call it from a command line. There are several arguments that can be used with this and I'll explain each of them.

From your command line you will use

Code: Select all

ustripper <package.u> -s -f -v

where <package.u> is replaced with the name of your compiled mod. The arguments are as follows
-s strips the code
-f obfuscates the functions
-v obfuscates the variables

Once you run the program your .u file will now be saved as a stripped and obfuscated file. BE SURE to make a safe copy of the mod before you use UStripper on it so you have a backup. Again, I cannot stress have a safe copy of code, mods, etc in a safe place. I can promise you that you WILL need them at some point because you messed up somewhere.

And finally here is the program

UStripper.7z

(7.76 KiB) Downloaded 565 times

Whew. Thanks for hanging in there with me. I hope you find this interesting and I'm open to answering any questions you might have. You can ask here or privately.

[Nelsona]

Umm, all right, to be honest I'm not entirely against these methods because sometimes they are a need to be done.

However, I have as usual small questions addressed at coders which were using to mess packages and/or "obfuscating" them. What is about more exactly ? First older than an old man is default MapVoteLA13. Provided in rental servers as default stuff, this thing which is aiming server-client has to be placed in client too.
Why ? Because if client has a fresh UT install with NOTHING added, in a server using this "Mutator" at first encounter client is crashing like an ass trying to decompress the uz file received from redirect and/or trying to load it. For clarification we can do a simple check with ucc.exe.

• ucc packageflag MapVoteLA13.u

Obviously if we are using another package, the result will show file flags and 0 errors message. For MapVote will show some Lousy Crap - more exactly an UCC crash.
If obfuscating a package means messing up packages intended for client do not expect me to use this way of doing. Also we might have various different methods against noob coders which are good only at thievery rather than writing new small stuff.
We can write some lousy script un-compilable and using variables written with different letters and classes names... really long. UTPT is crashing at facing "large" stuff and or messed up chars but final package won't do pain, we can keep going by stripping parts and or writing dumb things around. Only pro coders might deal here and even them might have issues because a script written in a jester style might badly annoy them.
Probably obfuscation used as "ServerSide" is a recommended thing. But... if this Server-Side stay in server not released in public, then obfuscation is pointless. I have some stuff which is resident in server and for sure I don't need it stripped/obfuscated - I might want to recover it someday due to an accidental possible work-station crash...
Another a little bit confusing way is using nasty class names (like aaaoootttt bbbnnnnnfff lllkkkkk) which are little time-consuming to figure what they do and not everyone has patience nowadays... eh...
I still have to figure what Higor's obfuscator does, but this is not a priority at this moment...

[Kelly]

A lot of your concern boils down to what I was talking about earlier: you absolutely need to ensure that you do not obfuscate replicated values that will leave the sandbox of the mod proper. I poked around quite a bit with this and it does generate some weirdness if you try to push this concept to see how far you can go. Most mods that need to be added to ServerPackages just can't be totally obfuscated because of this. You have to be careful. Good examples of this are many of the anticheat packages that are available to look at that are obfuscated. When you see certain variables that are "in the clear" and some that are not you have to ask yourself why the person did it this way. It's very likely they needed to have that variable available in a useful form.

I want to be very clear here about how I feel concerning this whole discussion. I think hiding your code is almost never a good idea. I've released at least a hundred mods/maps/etc and out of those I have obfuscated exactly two. One is the CAC anticheat and the other is a test mod I posted to show how hard it was to recover data from an obbed mod. Which, BTW it took Wormbo to break the obfuscation and reply with the value I had hidden. That should tell you how hard it is to recover when you follow the above steps.

Anyway I think it's a bad idea to obfuscate or strip damn near anything you do. At the very least it's rude and in more extreme situations it can be dangerous because you could do things to a client and they would be unaware and unable to find out. Still it's a good idea for coders to understand everything available and the how's-and-why's of the concepts. I'm going to post a further (VERY carefully worded) lecture on package flags and bytehacking using chocopackageedit and how cheaters are bypassing existing mods. I'm pretty sure I can show the how part without making it easy to understand or accomplish unless you have previous knowledge of hex editing. Really if you totally understand the architecture of UT's machine script you already know how to do it and I'm not saying anything you don't already know. If you are wanting to learn how to do it then good luck with that. If you think there is little written about how to properly obfuscate then go ahead and try to google almost anything about UT's machine code structure. Almost every search will return me when I was posting about learning it. Aside from that it just doesn't exist. I'm not going to change that either, I just want to explain what is possible if you apply the tools to try to exploit the system.

[Nelsona]

I gotta admit I think I have a deduction how to mock packages in player's advantage..., but this part for me is not a goal to complete. I'm thrilled how much work is around recovering badly messed up Levels and the rest. Of course reading this topic is way constructive and a good-to-know chapter...