Flash AS3 Class injection via Loader

I discovered a new technique for hacking flash games a month or so ago. I've been referring to it as class overriding (simply because class injection could be used to refer to injecting bytecode into a SWF).
It's a fairly simple technique that allows you to have extreme control over a loaded SWF.
I was going to do this tutorial on an actual game, but unfortunately there weren't any games that were good examples, so instead I modified my Unhackable Engine base (designed to be the simplest game possible for testing new security measures/ect in a semi-real environment and easy to port to other languages, the original AS3 version is under 90 lines of code, and the AS2 version is less than 60).
I'm going to assume you have some experience with AS3 and flash. If you don't, the source for this tutorial will be available.

Be warned, this SWF was botched together as fast as possible, and modified to function in weird ways specifically for the tutorial. Don't judge me on the quality of it's code.

Download the "game" used in this tutorial here.

 Anyways, to the tutorial:

The first thing we do is we start with a basic loader template that will load the SWF.

Create a new document class (I called mine Overrider), and put this code in it:

 package {  
      import flash.display.MovieClip;  
      import flash.display.Loader;  
      import flash.net.URLRequest;  
      import flash.system.ApplicationDomain;  
      import flash.system.LoaderContext;  
      public class Overrider extends MovieClip {  
           private var ldr:Loader = new Loader();  
           public function Overrider() {  
                this.addChild(ldr);  
                var urlReq:URLRequest = new URLRequest("unhackable.swf");  
                ldr.load(urlReq,new LoaderContext(false,ApplicationDomain.currentDomain));  
           }  
      }  
 }  

This will load the SWF into our SWFs ApplicationDomain, meaning that classes will be loaded into the same space, and when flash player tries to load a class that already exists in the current ApplicationDomain, the new class is dropped, and the old one remains (which is how this hack works).
Now, compile and run that, and you will get an error.

 TypeError: Error #1009: Cannot access a property or method of a null object reference.  
      at Unhackable()  

let's open unhackable.swf with a decompiler, and see what the problem is.
We know from the error that the error is within Unhackable(), so let's look at the code:

 public class Unhackable extends MovieClip  
 {  
   ...  
   public function Unhackable()  
   {  
     this.player = new Player(int(Math.random() * 300) + 50, int(Math.random() * 200) + 50);  
     this.money = new Money(int(Math.random() * 300) + 50, int(Math.random() * 200) + 50);  
     this.score = new ScoreKeeper();  
     addChild(this.score);  
     addChild(this.money);  
     addChild(this.player);  
     stage.addEventListener(Event.ENTER_FRAME, this.gameLoop);  
     return;  
   }  
   ...  
 }  

Ah, there's our problem. Let me explain for those of us who are unfamiliar with the bugs in the Loader class...
When A SWF is loaded normally (without the Loader class), the document class's constructor is called after it has been added to the stage and therefore has the stage property set. When a SWF is loaded with the Loader class, the document class's constructor is called before it has had it's stage property set, so that refference to the stage:

 stage.addEventListener(Event.ENTER_FRAME, this.gameLoop);   

will throw an error, because the stage variable is still a null object reference (it's null), and as the error states, you cannot access a method of a null object reference.

Luckily, we can fix this quite easily with class overriding.

Create a new class in your default package called Unhackable and copy and paste the code the decompiler generated for that class over.

Now, when you compile that, you'll get about a half-dozen errors. this is ok, and completely normal in class overriding. You see, that class imports other classes (Player, Money, ScoreKeeper) that we don't have in our project. The first solution you probably think if would be to decompile and add every class in the SWF, but that would be a pain in the ass and counterproductive, so we're gonna hack our way through this. the question we need to answer is: How do we access a class we can't import? The solution is simple: using the getDefinitionByName function in flash.utils.*.
so, replace:

 import UnhackableEngine.*;  

with:

 import flash.utils.*;  

getDefintionByName will dynamically find the class for us whenever we need it. so, with a little modification we can fix this class.
replace:

     private var player:Player;  
     private var money:Money;  
     private var score:ScoreKeeper;  

with:

           private var Player:Class = getDefinitionByName("UnhackableEngine.Player") as Class;  
           private var Money:Class = getDefinitionByName("UnhackableEngine.Money") as Class;  
           private var ScoreKeeper:Class = getDefinitionByName("UnhackableEngine.ScoreKeeper") as Class;  
           private var player:Object;  
           private var money:Object;  
           private var score:Object;  

Also, since there are no references to  this new class you've added, by default it won't compile into your SWF, so go back to your document class, and under the class variable definitions, add:

 private var unhackable:Unhackable;  

When you try and compile, you'll get some more errors now, but that's OK, cause we're gonna have to replace the function they're in anyway.
So, onto replacing the function, fixing the stage reference problems and adding the needed type casting.
First, we're gonna move all the code in the constructor to another function, and make that function be called when the object has been added to the stage (using the ADDED_TO_STAGE listener).
replace:

           public function Unhackable()  
           {  
                this.player = new Player(int(Math.random() * 300) + 50,int(Math.random() * 200) + 50);  
                this.money = new Money(int(Math.random() * 300) + 50,int(Math.random() * 200) + 50);  
                this.score = new ScoreKeeper();  
                addChild(this.score as DisplayObject);  
                addChild(this.money as DisplayObject);  
                addChild(this.player as DisplayObject);  
                stage.addEventListener(Event.ENTER_FRAME, this.gameLoop);  
                return;  
           }  

with:

           public function Unhackable()  
           {  
                this.addEventListener(Event.ADDED_TO_STAGE,addToStage);  
                return;  
           }  
           private function addToStage(e:Event)  
           {  
                this.player = new Player(int(Math.random() * 300) + 50,int(Math.random() * 200) + 50);  
                this.money = new Money(int(Math.random() * 300) + 50,int(Math.random() * 200) + 50);  
                this.score = new ScoreKeeper();  
                addChild(this.score);  
                addChild(this.money);  
                addChild(this.player);  
                stage.addEventListener(Event.ENTER_FRAME, this.gameLoop);  
           }  

And now we add some type casting to fix the last 3 errors.
replace:

                addChild(this.score);  
                addChild(this.money);  
                addChild(this.player);  

with:

                addChild(this.score as DisplayObject);  
                addChild(this.money as DisplayObject);  
                addChild(this.player as DisplayObject);  

and compile. with any luck, you have no errors, it compiles, loads the SWF and runs perfectly!
If not, try download the source of the finished code and try and figure out what went wrong.

Congratulations! you've successfully overrided your first class!

Now, onto doing something useful.

We'll double player speed and make it so that each "money" pickup gives us 1,000 points.
First, we'll start with the money hack, because the player speed hack is a little more complicated (If you're feeling confident/bored, you can skip to the player speed hack, as it teaches more important stuff).

This one is simple and straightforward.
you'll need a new package (class locations need to be mirrored) called UnhackableEngine, and in there a new class called ScoreKeeper.

Copy and paste the ScoreKeeper code from the decompiler, add this line of code to your document classes variable definitions to make sure it gets compiled in:

 private var scoreKeeper:ScoreKeeper;  

and compile.
You'll get an error.
Don't worry, it's easy to fix.

Our problem is that variables are not being casted from int/whatever to string, so the compiler is getting shitty with us.

replace the two occurrences of:

 score.text = gameScore;  

with:

 score.text = String(gameScore);  

and compile.
It should compile and work without errors.

Now, let's take a look at the addMoney function:

     static function addMoney()  
     {  
       var _loc_2:* = gameScore + 1;  
       gameScore = _loc_2;  
       score.text = String(gameScore);  
       return;  
     }  

seems easy enough to modify. Let's chuck some 0s in there

     static function addMoney()  
     {  
       var _loc_2:* = gameScore + 1000;  
       gameScore = _loc_2;  
       score.text = String(gameScore);  
       return;  
     }  

and boom, money pickups now give us 1000 score.

Onto player movement, and advanced class overriding!
I'm sure you know the drill by now.
Create a new class in the UnhackableEngine package named Player.
C+P the code from the decompiler, add a reference to the class in your document class, try to compile and see what errors you get.

Ooh, we get a new, nasty one.

The definition of base class Thing was not found.

We have two options here, overriding the Thing class will solve this problem, but imagine if Thing extended another custom class, which extended another custom class, which ended up being a class chain 20  classes long? it would be impractical to override them all.

But how can you possibly get around it? you can't just dynamically extend classes. That goes directly against AS3s standards. Luckily, in AS3 there's this nasty little thing called the Proxy class that goes against all of AS3s conventions, and makes this possible.

Although we cannot actually dynamically extend classes, we can pretend we do using the Proxy class to dynamically pretend we have properties of classes which we actually don't.

I'm going to warn you now, everything's about to get messy. Which is why I'm stalling.

I guess I'll explain the Proxy class a little, seems like it's the best way to teach this.

The Proxy class allows you to dynamically change the behavior of an object. When set up, you can make it so that if a property is accessed and doesn't exist in an object, a proxy function is called that can deal with it. we use this functionality to make an object act as if it has the properties of another object by making any attempt to access a property that doesn't exist on the object go to the object it is pretending to extend.

Hopefully, the code will help explain what I mean for those who are still confused...

First thing we need to do is make the Player class extend the Proxy class.
replace:

 public class Player extends Thing  

with:

 public class Player extends Proxy  

now, add these variables to the Player classes variable definitions:

           public var extendedClass:Class = getDefinitionByName("UnhackableEngine.Thing") as Class;  
           public var extended:Object  

add these functions to the class:

  override flash_proxy function getProperty(name:*):*
  {
   return extended[name];
  }
  
  override flash_proxy function setProperty(name:*,value:*):void
  {
   extended[name] = value;
  }

  override flash_proxy function callProperty(name:*, ...rest):*
  {
   extended[name].apply(rest);
  }

these functions are the backbone of our Proxy hack. We don't actually need most (or any) of them. in most situations, you'll need them, though. There are more Proxy functions you may need in other circumstances, but these are the main ones.

We're gonna have to do quite a bit of modifying to make this class work with us.
Any internal references in the player class to the class it extends need to be changed.

replace:

     public function Player(param1, param2)  
     {  
       fillColour = 11141120;  
       this.playerX = param1;  
       this.playerY = param2;  
       this.addEventListener(Event.ADDED_TO_STAGE, this.addListeners);  
       super(param1, param2);  
       return;  
     }  

with:

           public function Player(param1, param2)  
           {  
                extended = new extendedClass(param1, param2);  
                extended.fillColour = 11141120;  
                extended.drawStuff();  
                this.playerX = param1;  
                this.playerY = param2;  
                extended.addEventListener(Event.ADDED_TO_STAGE, this.addListeners);  
                return;  
           }  

and

     public function doMove()  
     {  
       this.playerX = this.playerX + this.xVel * 5;  
       this.playerY = this.playerY + this.yVel * 5;  
       drawX = this.playerX;  
       drawY = this.playerY;  
       drawStuff();  
       return;  
     }  

with:

           public function doMove()  
           {  
                this.playerX = this.playerX + this.xVel * 5;  
                this.playerY = this.playerY + this.yVel * 5;  
                extended.drawX = this.playerX;  
                extended.drawY = this.playerY;  
                extended.drawStuff();  
                return;  
           }  

and

     private function addListeners(event:Event) : void  
     {  
       stage.addEventListener(KeyboardEvent.KEY_DOWN, this.keyDownListener);  
       stage.addEventListener(KeyboardEvent.KEY_UP, this.keyUpListener);  
       return;  
     }  

with:

           private function addListeners(event:Event):void  
           {  
                extended.stage.addEventListener(KeyboardEvent.KEY_DOWN, this.keyDownListener);  
                extended.stage.addEventListener(KeyboardEvent.KEY_UP, this.keyUpListener);  
                return;  
           }  

As you can tell, the Proxy hack can be a bit messy. sometimes, it's better to just override the class it extends as well. cause now where up to the next problem: type casting.
A Proxy object can't be casted to anything the object it's pretending to extend can. And the addChild function which the player object is given as a parameter to expects a DisplayObject. luckily, we're already overriding the class that calls the function, so go back to the Unhackable class and
replace:

 addChild(this.player as DisplayObject);  

with:

 addChild(this.player.extended as DisplayObject);  

compile that and it should work error-free.

The Player class is FINALLY set up for modification (again, the proxy hack isn't really made for this situation, but it's useful to know how to do it).

One quick modification and we'll  have double player speed.

change

                this.playerX = this.playerX + this.xVel * 5;  
                this.playerY = this.playerY + this.yVel * 5;  

to

                this.playerX = this.playerX + this.xVel * 10;  
                this.playerY = this.playerY + this.yVel * 10;  

And we're done!

Download the source for this tutorial here.

A momentary lapse of progress

So, what's that running through your head right now? something on the lines of "Hey, Bmanatee, you haven't updated this blog in a while... are you dead? What's happening with BPE?" I bet. No? well, why the hell isn't it?

Anyway, BPE has been put on hold while I study for exams (I'll continue working on it near the end of November).
With any luck, strait IP hooks will be added next release (in the form of my pre-hook system). And hopefully I'll do some more work on PEW files, too.
When that's all done and dusted, and I feel the plugin system has been developed enough, I'll move from Pre-Apha phase to Alpha phase and start working on the analyzer part of BPE.

I'm also going to try and write some more complicated plugins for games when I get the time, maybe even a packet-based aimbot. Maybe I'll write a plugin for a game with some basic connection security (eg. data + hash, which would conventionally be nigh impossible to edit using a packet editor without completely replacing the packet).

BPE Plugin Writing Tutorial #1 (Writing your first plugin)

So, I thought it was about damn time I wrote a tutorial on writing plugins for BPE (Mostly because currently I'm the only person who knows how).
Firstly, I've been updating the Wiki, so hopefully between this tutorial and the Wiki, there should be enough information for people to start writing plugins.
 and now the tutorial:

Writing your first plugin.

So, we're  gonna make a nice, simple plugin that simply outputs everything happening on the servers/ports being listened to.
It'll do the following:
Properly set up it's window
Output all sent/recieved packets
Output when connections are opened/closed

Now, let me explain a little about the hook system BPE uses. there are two kinds of hooks:
Hooks called by BPE, and
Hooks called by the plugin.

Hooks called by BPE are utilized by creating a public function in the document class of the plugin.
eg:

 public function sendPacketHook(packet:ByteArray,socketID:int):ByteArray  
 {  
     output.appendText("["+socketID+"] Sent:"+packet+"\n")  
     return packet;  
 }  

That above code would be called every time a packet is sent by the client. the variable "packet" contains the payload (data) from the packet in the form of a ByteArray. socketID is an integer containing the ID of the socket. The function returns the unmodified packet, so no modification is made.

Hooks called by the plugin are utilized by creating a public Function variable in the document class of the plugin, and then calling that variable/Function when you need to.
eg:

 public var updateWindow:Function;  
 public function someFunction():void  
 {  
     updateWindow(550,400,"Debug");  as
     return;
 }  

That above code (when someFunction is called) will scale the size of the window so that the stage is 550 pixels wide and 400 pixels high, then set the plugins window title to say "Debug".

Also note that all used hooks must be specified in the .pep file that goes with the plugin (more on that later, though).

Anyways, I hope that's enough explanation for understanding the hooking system for now. let's get on to making the actual plugin!
I'm going to assume you know your way around Flash and know a little AS3 at this point.
So, create a new AS3 project and a document class called "BPEDebugPlugin".
now, we're gonna be using ByteArray's (for the sent and received data) and TextFields (for the output), so go ahead and add these lines to the includes:

     import flash.text.TextField;  
     import flash.utils.ByteArray;  

Now, we're gonna need to declare a couple variables in the class.
Firstly, since we want to set the window size and title, we want to use the updateWindow hook, so we need to add a Function variable with the name updateWindow.
Secondly, we want a TextField that we can write our outputted data to.
so, add these lines to your class variable declarations

         public var updateWindow:Function;  
         private var output:TextField = new TextField();  

we're gonna make use of the finishPluginSetup hook. this simple hook function is called after your plugins hooks have been set up and your plugin has been added to the stage. it basically tells you it is now safe to use hooks and access the stage.
Chuck this code right after the end of your constructor function:

         public function finishPluginSetup()  
         {  
             updateWindow(550,400,"Debug");  
             output.x = 20;  
             output.y = 20;  
             output.width = 510;  
             output.height = 360;  
             output.background = true;  
             output.backgroundColor = 0xAAAAAA;  
             output.text = "Output\n";  
             this.addChild(output);  
         }  

As stated before, this function will be called once, when BPE has added it to the stage and set up all it's hooks. it calls the updateWindow hook and changes the window size and label. it will then set up the output TextField for use.

Now, let's get to the actually useful hooks. We'll start with the send and receive hooks, since they're super-similar, and quite simple.

         public function recievePacketHook(packet:ByteArray,socketID:int):ByteArray  
         {  
             output.appendText("["+socketID+"] Recieved:"+packet+"\n")  
             return packet;  
         }  
         public function sendPacketHook(packet:ByteArray,socketID:int):ByteArray  
         {  
             output.appendText("["+socketID+"] Sent:"+packet+"\n")  
             return packet;  
         }  

These functions will be called by BPE every time a packet is sent by the client or received by the client. packet is the ByteArray containing the data payload of the packet, and socketID is the ID number for the socket. We'll output the data being sent in the packet.
This is probably a good time to introduce you to BPE's socket ID system. each socket that connects to BPE is given an ID to make them easy to keep track of.
The first socket to connect is given the ID 0
the second 1
the third 2
ect.
The functions then output the sent/recieved data along with the socket ID.
The ByteArray returned by these functions is then run through any remaining plugins and either sent to the client or server depending on whether the packet is being received or sent.
Since we're returning the same, unmodified ByteArray that was the input of the function, the packet is left untouched. if you return an empty ByteArray, the packet is dropped.

Onto the socketOpen and socketClose hooks.

         public function socketOpenHook(socketID:int,address:String,port:int):void  
         {  
             output.appendText("["+socketID+"] Connected to:"+address+":"+port+"\n")  
             return;  
         }  

The socketOpenHook is run every time a socket connects to BPE. it gives you the new socket's ID, the address it's attempting to connect to and the port on which it's attempting to connect to. We'll output the address and port on the server it's attempting to connect to.

Next is the socketCloseHook.

           public function socketCloseHook(socketID:int,closeSocket:Boolean):Boolean  
           {  
                output.appendText("["+socketID+"] Disconnected, "+closeSocket+"\n")  
                return closeSocket;  
           }  

The socketCloseHook is called when the server disconnects the client. The Boolean closeSocket tells you whether BPE plans on disconnecting the client. if true, the socket is to be disconnected, if false, the socket connected to the client will stay connected. We'll return the closeSocket value given to us to let the other plugins or BPE decide what to do with the socket connected to the client.

Now, compile that sucker and we're up to creating the .pep file to load our plugin.

PEP files are like an external header for the plugin. it tells BPE everything it needs to know to run your plugin.
I created a simple little tool making it easy to generate the .pep file for your plugin. you can get it here or on the downloads page.
Open the PEP Builder up (do it in your browser if you have to).
For plugin name, type "BPEDebug".
For SWF Filename, write the name of your SWF (mine is "BPEDebug.swf")
and we need to tick the box next to each hook we used
tick the box next to hookUpdateWindow, hookFinishPluginSetup, hookRecievePacket, hookSendPacket, hookSocketOpen and hookSocketClose.
Once you've done that, click the "Save PEP File" button, and save it to the same location as your plugin SWF.

You're done!
Load your plugin with BPE, hook a server and port (web servers are the easiest for testing),  and if it works, give yourself a pat on the back.
If it doesn't work, try again or  leave a comment.

Here's a link to my finished source.

BROPlugin release

Made a new plugin. BROPlugin, a hack for XGen's game Blast Rage Online.
 you can download it here or from the Downloads page.
Currently, it only has Godmode. I might add my reload and wall hack at a later date.
To run this, you'll need Adobe Air and BPEV1.1.
you need to hook www.xgenstudios.com on port 80 to make this work.
Here's a quick video tut on how to set it up.

It's not open-source cause that would make it too easy to patch

BPE Pre-Alpha V1.1

It's finally here!
BPE Pre-Alpha V1.1 and HTTPlugin are done.
I'm tired from programming and testing, so I'm not gonna write much.
Read the readme if you want more.

Find HTTPlugin and the latest version of BPE on the Downloads page.
get BPE Pre-Alpha V1.1 here.

I'm gonna spend any upcoming spare time to write tutorials and update the wiki.

Changelog:
 - changed updateWindowHook
 - added socket ID system
   - updated sendPacketHook
   - updated recievePacketHook
 - added forceRecieveHook
 - added forceSendHook
 - added forceCloseHook
 - added socketOpenHook
 - added socketCloseHook
 - removed PEPAPI V1 support, mostly
 - attempted to make work on Linux and Mac (untested)
 - GUI improvements
   - added "Server Options" window
   - added "Plugin Options" window (incomplete)
   - added "Port Options" window (incomplete)
 - fixed bugs
   - possibly fixed the "multiple hooked servers" bug? (not sure how, might be black magic. the bug should theoretically still be there, but tests indicate it's fixed)
   - fixed problem with data not being sent when a connection was still being fowarded
   - misc other bugs

If I get a Mac tester, I'll try and get Linux and Mac support into the next release.

Packet Editor Progress #6

Things are going well towards the release. probably only about a week remaining.
I have some pretty heavy stuff going on in my life right now, so progress will probably slow down. however, HTTPlugin is working almost perfectly. just one or two small features to implement and then I'll release it with BPE Pre-Alpha V1.1.
Here's a pretty pic of HTTPlugin:

It can redirect HTTP requests to any location (online or offline). it has many uses, one of which being working as a more advanced version of my sitelocked game loader.
Hopefully I can get BPE running on Linux and Mac before the release...

Packet Editor Progress #5

So, it's been a few weeks. I'm starting to get near the next release. about time, too.
Fixing the multiple server hooks bug may have to be postponed, but I've added many more hooks which should hopefully be operational by the next release. Currently, all the plugin hooks are:
(Current, PEPAPI v1)
updateWindow (Called by the plugin, changes window width, height and title)
sendPacketHook (Called by the Core, every time the client sends a packet, allows viewing and modification of the sent data)
recievePacketHook (Called by the Core, called every time the client receives a packet, allows viewing and modification of the received data)
finishPluginSetup (Called by the Core, called after the plugin has been set up, when it is safe for it to start using hooks)
(New, PEPAPI v1.1)
forceRecieveHook (Called by the plugin, allows the plugin to force the client to receive data, crafts a packet sent to the client)
forceSendHook (Called by the plugin, allows the plugin to force the client to send data, crafts a packet sent to the server)
forceCloseHook (Called by the plugin, forces a socket to close)
socketOpenHook (Called by the Core, called every time a socket is opened)
socketCloseHook (Called by the Core, called every time a socket is closed)

Several old PEPAPI v1 hooks will be changed to use the new SocketID system. all hooks are currently in flux, and may very well be drastically changed several times over the next few releases.

Oh, and there's a Wiki now:
http://bpe.wikia.com/wiki/Bmanatee%27s_Packet_Editor_Wiki

Hopefully, I'll do some work on the wiki after this next release, since there should be enough hooks now to make some useful plugins.


Also, if there are any Linux or Mac users who would like to become testers, please contact me.

*edit*
today's one of those days where everything works.
Fixed a dozen bugs. Got my HTTPlugin proof-of-concept working. looks like I'm almost ready for the next release (although, I'd prefer to finish HTTPlugin first, so that there's some example code for the new hooks).