Exception Decoding and Stack Trace Resolution

When your application is protected with Shield, exception messages and stack traces may be obfuscated. ByteHide provides several ways to decode and resolve these exceptions for debugging and support.

Requirements

To decode exceptions, you will need:

• Your Project Token
• Your ProtectionSecret (set in your Shield configuration)

Finding the ProtectionSecret

The ProtectionSecret is now set by you in the Shield configuration file (see the configuration documentation for details). This secret is used to enable advanced debugging and exception decoding features.

• Set the ProtectionSecret in your configuration: Add the ProtectionSecret property to your Shield configuration file.
• If you do not set a secret: You can obtain the secret for your protected application directly from the ByteHide web panel.

Decoding an Exception Online (API)

Shield provides an API to decode obfuscated stack traces from any browser or tool.

Endpoint:

GET https://shield.microservice.bytehide.com/api/applications/<project-token>/<your-protection-secret>?trace=<obfuscated-trace>

• <project-token>: Your Project Token (from your ByteHide project)
• <your-protection-secret>: Your ProtectionSecret (see your configuration file)
• <obfuscated-trace>: The obfuscated stack trace or exception message (plain text, URL-encoded)

Response Codes:

• 404: The application corresponding to the secret or project token is not found or has been deleted
• 404: The exception cannot be deobfuscated with the provided secret
• 200: The original exception/stack trace message (plain text) is returned

Decoding via the Web Panel

You can also decode stack traces directly from the ByteHide web panel:

1. Go to your project in the ByteHide dashboard
2. In the history section, click the three dots (actions) for a build
3. Select Deobfuscate trace
4. Paste your obfuscated stack trace and click Deobfuscate Trace

This will return the original, readable stack trace.

Automatic Deobfuscation with ByteHide.ToolBox

The ByteHide.ToolBox SDK can automatically deobfuscate all exceptions in your application. Just call SubscribeToExceptionEvents() once at startup:

namespace Sample;

internal class Program
{
    internal static void Main()
    {
        try
        {
            var toolbox = Bytehide.ToolBox.Products.Shield;
            toolbox.SubscribeToExceptionEvents();

            throw new Exception("This is a test exception");
        }
        catch (Exception ex)
        {
            Console.WriteLine("Caught Exception [Message]: " + ex.Message);
            Console.WriteLine("Caught Exception [StackTrace]: " + ex.StackTrace);

            Console.ReadLine();
        }
    }
}

This will ensure all exceptions are automatically deobfuscated.

Manual Deobfuscation with ByteHide.ToolBox

You can also manually deobfuscate exceptions using the Deobfuscate() extension method:

using Bytehide.ToolBox.Shield.Core;

namespace Sample;

internal class Program
{
    internal static void Main()
    {
        try
        {
            throw new Exception("This is a test exception");
        }
        catch (Exception ex)
        {
            ex = ex.Deobfuscate();

            Console.WriteLine("Caught Exception [Message]: " + ex.Message);
            Console.WriteLine("Caught Exception [StackTrace]: " + ex.StackTrace);

            Console.ReadLine();
        }
    }
}

Note: In this mode, you must call Deobfuscate() in each catch block where you want to resolve the stack trace.

Magic File Requirement

For both automatic and manual deobfuscation with the SDK, you must place your magic file (bytehide.shield.magic) in the same directory as your protected assembly (.dll or .exe).

For more information on obtaining the magic file, see Obtaining the Magic File.

Logs and Troubleshooting

Detailed logs of the protection and deobfuscation process can be found in the logs folder located in your assembly directory. These logs can help diagnose issues with exception decoding or SDK integration.