Debugging and managing exceptions after protection
Shield offers the necessary solutions for you to use and manipulate a protected application just like the original one.
To give some context, this section of the documentation aims to answer the following questions:
- I have protected my application, but when it reports an exception everything is encrypted and I have no way of knowing where the error comes from.
- After protecting my application with Shield, no attacker can debug it, but... How do I debug my own protected application?
- I am using a service to manage and report the exceptions of my application, but it only receives obfuscated code.
- I have a .pdb file of my original application, but it does not work with the one protected with Shield.
If the renaming protection is not used, none of this is necessary, since the .PDB and application names will remain original.
Resolving exceptions from a protected application
By default, Shield maps the renamed symbols of your application, but if you want to guarantee this feature, please use the decodeable mode in the rename protection. To do this, see:
Shield for .NET automatically maps the original members of your application along with the obfuscated ones in order to be able to resolve the original exception messages and stack traces.
To perform security actions like this, it is always necessary to have the security key of the protection process at hand. This is a key that is generated for the account owner for each protected application and allows access to sensitive functions such as the following.
Finding the security key
The security key of an application is sent by email to the account owner when an application is protected. You will see an email that looks like this:
Decoding an exception online
Shield has an API that allows you to obtain an original stack trace based on an obfuscated one directly from any browser.
To do this, call:
- SECURITY_KEY: must be your security key, see: finding the security key
- EXCEPTION: The (plain text) message of the exception or the obfuscated stack trace (plain text).
When the response will be:
- 404: The application corresponding to the security key is no longer found (It has been deleted from your web panel)
- 404: The exception cannot be deobfuscated; the security key cannot be used to decrypt this application.
- 200: You will receive the original exception/stack trace message (plain text) back.
You can use this PlayGround or call the API from your own application to resolve stack traces dynamically. If you use an exception resolution service, you can add the API call to the service and replace the original exception with the obfuscated one.
Debugging a Shield-protected application
Now, if you want to be able to debug your application (which contains an anti-debugger), do the following:
Obtaining the security key file
- Get your security key as specified in: finding the security key
- Call the following endpoint:
- SECURITY_KEY: must be your security key (point 1)
- If your key is correct, a file called bytehide.shield.master.key will be downloaded.
Debugging your application
With the previously exported key, follow these steps:
- Place the bytehide.shield.master.key file next to the folder (same directory) where your protected application is running.
- You will automatically be able to debug your application from Visual Studio or another debugging software.
Do not share your security key or bytehide.shield.master.key file with anyone, keep it in a safe place, and do not publish or deploy your application along with this file.
If you provide the original .pdb file when protecting your application, the .pdb file generated by Shield will be automatically exported to the directory where your protected application is saved or included in the web panel download.