Mitmdump Bug: Silent Script Unload On Argument Parsing Failure

Dec 4, 2025 by Admin 63 views

Hey guys! Ever run into a situation where your mitmproxy scripts just… stop working without any explanation? Well, it seems there's a sneaky little bug that might be the culprit. Specifically, when mitmproxy fails to parse arguments for your custom scripts, it silently unloads the script, leaving you in the dark. Let's dive into this issue, explore the expected behavior, and see how to reproduce it.

The Silent Script Unload Problem

The core of the problem lies in mitmproxy's handling of script arguments. When you use the --script flag to load your custom Python code, you can define additional options with specific types. However, if the value you provide for an option cannot be parsed as the designated type (e.g., trying to set a boolean option to a numeric value), mitmproxy unloads the script without any warning. This silent failure can be incredibly frustrating, as there's no logging to indicate what went wrong, making it difficult to debug. This behavior is definitely not what we want, and it's something that needs to be addressed. It's like your favorite tool suddenly stops working, and you're left guessing why.

The issue affects mitmproxy version 12.2.1 and potentially earlier versions. Imagine you're building a mitmproxy extension to automatically modify requests, but then it stops working, and you don't receive any error. This is so annoying, right?

Expected vs. Actual Behavior

Let's clarify what we expect to happen. Ideally, when there's an issue with argument parsing, mitmproxy should provide informative logging. At a minimum, it should log an error indicating that an option failed to be processed. Even better, it should also log that the script has been unloaded. This would provide valuable feedback to the user, guiding them toward the root cause of the problem. This is the expected behavior: Clear error messages and script unload notifications.

Reproduction Steps

To see this bug in action, follow these steps:

Create a simple plugin: Create a Python file (e.g., plugin.py) with the following content:

from mitmproxy import addonmanager
from mitmproxy import ctx
from mitmproxy import http

class Plugin:
    def load(self, loader: addonmanager.Loader):
        loader.add_option("shout", bool, False, "use caps")

    def request(self, flow: http.HTTPFlow):
        print("request processing")
        if ctx.options.shout:
            print("HELLO")
        else:
            print("hello")

addons = [Plugin()]

This code defines a mitmproxy plugin that uses a custom option named shout of type boolean. The plugin will either print HELLO or hello based on the value of the shout option.

Test with default options: Run mitmdump with the script, and you'll see the expected logging:
```
./mitmdump --script plugin.py
```
You should see request processing and hello printed, as the shout option defaults to False.
Test with a valid boolean value: Set the shout option to true:
```
./mitmdump --script plugin.py --set shout="true"
```
Now, you should see request processing and HELLO printed, as the option is correctly parsed.
Test with an invalid value: Finally, try setting the shout option to an invalid value (e.g., 1):
```
./mitmdump --script plugin.py --set shout="1"
```
In this case, you will observe the bug: The script is silently unloaded, and no HELLO or hello is printed. You'll only see the standard mitmproxy output, without any indication of a problem.

By following these steps, you can easily reproduce the bug and witness the silent script unload firsthand. This is a critical issue because it hinders the ability to debug and maintain mitmproxy scripts effectively.

System Information

The bug was identified in the following environment:

Mitmproxy: 12.2.1 binary
Python: 3.14.0
OpenSSL: OpenSSL 3.5.4 30 Sep 2025
Platform: Linux-6.16.12-with-glibc2.41

This setup provides the context for the issue. The behavior could be reproducible on other platforms or versions. The key is the interaction of mitmproxy and how it handles command-line arguments.

The Impact of Silent Failures

The impact of this silent failure is significant. Without any error messages, debugging becomes a nightmare. You might spend hours trying to figure out why your script isn't working, only to discover that it was never loaded in the first place. This can lead to wasted time, frustration, and a decrease in productivity. The lack of feedback makes it incredibly difficult to identify and fix issues. The user is left in the dark, unable to determine the cause of the problem. This breaks the user's trust.

Imagine you are debugging a script that intercepts and modifies HTTP requests. If the script fails to load silently, your modifications won't occur, and you might assume your analysis is complete when it is not. This can lead to inaccurate results or a false sense of security. Also, for automation, it can be fatal.

Potential Solutions and Workarounds

While the ideal solution is for mitmproxy to provide clear error messages and logging, here are some workarounds you can use in the meantime:

Input validation within your script: Add input validation to your script to check the types of the arguments. If you detect a problem, you can manually print an error message. This won't fix the underlying issue, but it can provide some debugging information. For example, inside your load function, you could check the types of the options and print errors if there's a mismatch.
Use a try-except block: Wrap the parts of your script that use the options in a try-except block. This can help you catch unexpected errors and provide some context for debugging. Catching TypeError or ValueError exceptions when using the options might give you insights into the argument parsing issue.
Carefully check your command-line arguments: Double-check the types and values of your command-line arguments to ensure they are compatible with your script's options. A simple typo can trigger this issue.
Keep an eye on mitmproxy updates: The best solution is for the mitmproxy developers to fix the bug. Keep an eye on the project's issue tracker and release notes for updates.

These workarounds can mitigate the impact of the silent failure, but they are not a replacement for proper error handling by mitmproxy.

Conclusion

This silent script unload bug in mitmproxy is a serious issue that can make debugging your scripts a challenge. By understanding the problem, reproducing the bug, and using the available workarounds, you can minimize the impact and continue using mitmproxy effectively. Let's hope the mitmproxy team addresses this soon to improve the user experience and make scripting with mitmproxy more robust!Remember to validate your input, use try-except blocks, and stay updated on mitmproxy releases. With these precautions, you'll be able to work more effectively with mitmproxy, even with this bug.