| Component | Status |
|---|---|
| Tests |  |
| Packages |   |
TaintMonkey is a a dynamic taint analysis library for Python Flask web applications. It leverages monkey patching to instrument Flask applications without modifying source code. TaintMonkey includes a built-in fuzzer that helps developers test endpoints for specific vulnerabilities with randomized inputs. This repository also comes with JungleGym, a datatset of 100+ example Flask applications susceptible to web vulnerabilities from the Common Weakness Enumeration (CWE).
To install the latest version of TaintMonkey, you can run the following command.
pip install taintmonkey
In order to test a Flask endpoint for a particular vulnerability with TaintMonkey, you must first create a plugin.
Monkey patch your endpoint's source to return a tainted string.
Example for OS Command Injection:
@patch_function("dataset.cwe_78_os_command_injection.insecure_novalidation.app.open_file_command")
def new_open_file_command(file: TaintedStr):
return TaintedStr(original_function(file))Write a taintmonkey() fixture that passes your app's verifier, sanitizer, and sink functions to the TaintMonkey class. TaintMonkey automatically monkey patches these functions to add taint analysis instrumentation. Next, initialize and set a fuzzer (dictionary, mutation, or grammar-based) for TaintMonkey to use.
Example:
VERIFIERS = []
SANITIZERS = []
SINKS = ["os.popen"]
@pytest.fixture()
def taintmonkey():
from dataset.cwe_78_os_command_injection.insecure_novalidation.app import app
tm = TaintMonkey(app, verifiers=VERIFIERS, sanitizers=SANITIZERS, sinks=SINKS)
fuzzer = MutationBasedFuzzer(app, "plugins/cwe_78_os_command_injection/corpus.txt")
tm.set_fuzzer(fuzzer)
return tmThe fuzzing harness is how a TaintMonkey plugin uses inputs generated by the fuzzer to test an endpoint for vulnerabilities. Use the fuzzer's context manager to get a TaintClient object and input generator. Then iterate through the generated inputs and make requests to the endpoint using those inputs.
Example:
def test_fuzz(taintmonkey):
fuzzer = taintmonkey.get_fuzzer()
with fuzzer.get_context() as (client, get_input):
for inp in get_input():
client.get(f"/insecure?file={inp}")Run the plugin to test if your Flask endpoint is vulnerable.
Example:
PYTHONPATH=. pytest -s plugins/cwe_78_os_command_injection/__init__.py
During execution, a TaintException is raised if tainted input reaches a sink without proper verification or sanitization (assuming that verifiers, sanitizers, and sinks have been correctly registered with the TaintMonkey object).
To download the necessary packages for TaintMonkey, run
pip install -r requirements.txt
We use ruff to check the formatting of our code so before submitting a Pull Request, make sure to run the formatter using the following command.
python -m ruff format --no-cache
To run the unit test suite, use the following command.
PYTHONPATH=. pytest tests/
To generate a coverage report of TaintMonkey, run the following commands.
PYTHONPATH=. pytest --cov=taintmonkey --cov-report html tests/
cd htmlcov/
python3 -m http.server
The HTML report generated by coverage-py should be available at http://localhost:8000.
In order to run experiments using the JungleGym dataset, make sure to set up the environment by doing the following.
python3 -m venv venv
source venv/bin/activate
bash experiments/setup.sh
TaintMonkey was developed by Shayan Chatiwala, Aiden Chen, Carter Chew, Sebastian Mercado, and Aarav Parikh for GSET 2025. The project was advised by Benson Liu as their project mentor and Anusha Iyer as their project Residential Teaching Assistant (RTA). For any questions or requests for additional information, please contact the authors.