{"id":30178125,"url":"https://github.com/bliutech/taintmonkey","last_synced_at":"2025-08-12T05:17:37.459Z","repository":{"id":306197931,"uuid":"1009991323","full_name":"bliutech/TaintMonkey","owner":"bliutech","description":"GSET 2025. Repository for \"TaintMonkey: Dynamic Taint Analysis of Python Web Applications Using Monkey Patching\". A Pytest plugin incorporating fuzzing and taint analysis to uncover security vulnerabilities in Flask web applications.","archived":false,"fork":false,"pushed_at":"2025-08-08T02:21:42.000Z","size":3356,"stargazers_count":13,"open_issues_count":13,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-08-08T04:09:10.214Z","etag":null,"topics":["dynamic-analysis","flask","fuzzing","monkey-patching","program-analysis","pytest","taint-analysis"],"latest_commit_sha":null,"homepage":"https://github.com/bliutech/TaintMonkey/blob/main/.github/paper.pdf","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bliutech.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-28T05:40:49.000Z","updated_at":"2025-08-08T02:21:42.000Z","dependencies_parsed_at":null,"dependency_job_id":"e2c7ea75-f402-4393-b25d-27e6bbfd31e3","html_url":"https://github.com/bliutech/TaintMonkey","commit_stats":null,"previous_names":["bliutech/taintmonkey"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/bliutech/TaintMonkey","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bliutech%2FTaintMonkey","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bliutech%2FTaintMonkey/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bliutech%2FTaintMonkey/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bliutech%2FTaintMonkey/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bliutech","download_url":"https://codeload.github.com/bliutech/TaintMonkey/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bliutech%2FTaintMonkey/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":270005591,"owners_count":24510939,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-12T02:00:09.011Z","response_time":80,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["dynamic-analysis","flask","fuzzing","monkey-patching","program-analysis","pytest","taint-analysis"],"created_at":"2025-08-12T05:17:36.225Z","updated_at":"2025-08-12T05:17:37.442Z","avatar_url":"https://github.com/bliutech.png","language":"Python","readme":"# TaintMonkey: Dynamic Taint Analysis of Python Web Applications Using Monkey Patching\n\n![TaintMonkey banner](https://raw.githubusercontent.com/bliutech/TaintMonkey/refs/heads/main/.github/taintmonkey_banner.png)\n\n| **Component** | **Status** |\n| ----------- | ----------------------------------------------------------------------------------------------------- |\n| **Tests**   | [![CI - Run Unit Tests](https://github.com/bliutech/TaintMonkey/actions/workflows/test.yaml/badge.svg)](https://github.com/bliutech/TaintMonkey/actions) |\n| **Packages** | ![Wheel](https://img.shields.io/pypi/wheel/taintmonkey.svg) [![PyPI](https://img.shields.io/pypi/v/taintmonkey.svg)](https://pypi.org/project/taintmonkey/) |\n\nTaintMonkey 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). \n\n![TaintMonkey components](https://raw.githubusercontent.com/bliutech/TaintMonkey/refs/heads/main/.github/taintmonkey_components.png)\n\n## Installation\nTo install the latest version of TaintMonkey, you can run the following command.\n\n```\npip install taintmonkey\n```\n\n## Usage\nIn order to test a Flask endpoint for a particular vulnerability with TaintMonkey, you must first create a plugin.\n\n![TaintMonkey dataflow](https://raw.githubusercontent.com/bliutech/TaintMonkey/refs/heads/main/.github/taintmonkey_dataflow.png)\n\n### Step 1: Monkey Patch the Source\nMonkey patch your endpoint's source to return a tainted string.\n\nExample for OS Command Injection:\n```python\n@patch_function(\"dataset.cwe_78_os_command_injection.insecure_novalidation.app.open_file_command\")\ndef new_open_file_command(file: TaintedStr):\n    return TaintedStr(original_function(file))\n```\n\n### Step 2: Create `taintmonkey()` Fixture\nWrite 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.\n\nExample:\n```python\nVERIFIERS = []\nSANITIZERS = []\nSINKS = [\"os.popen\"]\n\n@pytest.fixture()\ndef taintmonkey():\n    from dataset.cwe_78_os_command_injection.insecure_novalidation.app import app\n\n    tm = TaintMonkey(app, verifiers=VERIFIERS, sanitizers=SANITIZERS, sinks=SINKS)\n\n    fuzzer = MutationBasedFuzzer(app, \"plugins/cwe_78_os_command_injection/corpus.txt\")\n    tm.set_fuzzer(fuzzer)\n\n    return tm\n```\n\n### Step 3: Write The Fuzzing Harness\nThe 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.\n\nExample:\n```python\ndef test_fuzz(taintmonkey):\n    fuzzer = taintmonkey.get_fuzzer()\n    with fuzzer.get_context() as (client, get_input):\n        for inp in get_input():\n            client.get(f\"/insecure?file={inp}\")\n```\n\n### Step 4: Run Plugin\nRun the plugin to test if your Flask endpoint is vulnerable.\n\nExample:\n```\nPYTHONPATH=. pytest -s plugins/cwe_78_os_command_injection/__init__.py\n```\n\nDuring 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).\n\n\n## Development\nTo download the necessary packages for TaintMonkey, run\n```\npip install -r requirements.txt\n```\n\nWe 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.\n\n```\npython -m ruff format --no-cache\n```\n\nTo run the unit test suite, use the following command.\n\n```\nPYTHONPATH=. pytest tests/\n```\n\nTo generate a coverage report of TaintMonkey, run the following commands.\n\n```\nPYTHONPATH=. pytest --cov=taintmonkey --cov-report html tests/\ncd htmlcov/\npython3 -m http.server\n```\n\nThe HTML report generated by coverage-py should be available at http://localhost:8000.\n\n## Experiments\nIn order to run experiments using the *JungleGym* dataset, make sure to set up the environment by doing the following.\n\n```\npython3 -m venv venv\nsource venv/bin/activate\nbash experiments/setup.sh\n```\n\n## Authors\nTaintMonkey 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.\n\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbliutech%2Ftaintmonkey","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbliutech%2Ftaintmonkey","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbliutech%2Ftaintmonkey/lists"}