{"id":18561440,"url":"https://github.com/ivision-research/burpscript","last_synced_at":"2025-08-20T14:30:52.585Z","repository":{"id":238571815,"uuid":"795625291","full_name":"ivision-research/burpscript","owner":"ivision-research","description":null,"archived":false,"fork":false,"pushed_at":"2024-12-03T21:10:59.000Z","size":130,"stargazers_count":57,"open_issues_count":0,"forks_count":1,"subscribers_count":3,"default_branch":"main","last_synced_at":"2024-12-03T21:35:34.640Z","etag":null,"topics":["burp-extensions","burp-plugin","burpsuite","scripting"],"latest_commit_sha":null,"homepage":"","language":"Kotlin","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ivision-research.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","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}},"created_at":"2024-05-03T17:17:17.000Z","updated_at":"2024-12-03T21:11:03.000Z","dependencies_parsed_at":"2024-06-11T18:52:43.112Z","dependency_job_id":"c6beb761-85df-4ef7-a1d2-f21e996307e5","html_url":"https://github.com/ivision-research/burpscript","commit_stats":null,"previous_names":["ivision-research/burpscript"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ivision-research%2Fburpscript","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ivision-research%2Fburpscript/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ivision-research%2Fburpscript/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ivision-research%2Fburpscript/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ivision-research","download_url":"https://codeload.github.com/ivision-research/burpscript/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":230431100,"owners_count":18224655,"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","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":["burp-extensions","burp-plugin","burpsuite","scripting"],"created_at":"2024-11-06T22:06:56.902Z","updated_at":"2025-08-20T14:30:52.573Z","avatar_url":"https://github.com/ivision-research.png","language":"Kotlin","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Burpscript\n\nBurpscript adds dynamic scripting abilities to Burp Suite, allowing you to write scripts in Python or Javascript to manipulate HTTP requests and responses.\n\nFeatures:\n\n- Python 3 and JavaScript support\n- Manipulate requests and responses from the Proxy or other tools such as the Repeater\n- Conditionally drop requests \u0026 responses, or send them to the Intercept tab for manual inspection\n- Hot reloading of scripts on file change\n- Quickly enable/disable scripts\n- Built-in cryptographic utilities\n- Filter DSL for easily determining if the plugin's registered handlers should handle a request or response\n\n## Installation\n\nThe best way to build this project is to enter the `nix` development environment and then use the build script.\n\n```sh\n$ nix develop\n# Build with Python support\n$ ./build.sh\n# Build with both Python and JavaScript Support\n$ ./build.sh --js --python\n```\n\nIf you don't want to use `nix`, you'll need to have `gradle` installed and can just run `./build.sh` without it, but this may cause issues with different `gradle` versions.\n\nThe resulting jar file will be in `build/libs/burpscript-plugin-\u003cversion\u003e.jar`, which you can then install into Burp Suite through the Extensions -\u003e Add window. For more information, see [Managing extensions](https://portswigger.net/burp/documentation/desktop/extensions/managing-extensions).\n\n## Usage\n\nBurpscript supports writing scripts in JavaScript or Python. When a script is added, Burpscript will call specially named handler functions defined in the script when a request or response is received, allowing scripts an opportunity to manipulate them as they pass through the proxy. Scripts can also define filter expressions using a [Lisp-like DSL](FILTER_EXPRESSIONS.md) to determine which requests and responses they should be applied to.\n\n**References**\n\n- The [examples](examples) directory\n- The [ScriptHttpRequest](src/main/kotlin/com/carvesystems/burpscript/ScriptHttpRequest.kt) and [ScriptHttpResponse](src/main/kotlin/com/carvesystems/burpscript/ScriptHttpResponse.kt) classes. These define the API that scripts can use to modify requests and responses.\n- [Burp Montoya API Javadoc](https://portswigger.github.io/burp-extensions-montoya-api/javadoc/burp/api/montoya/MontoyaApi.html). In particular, [HttpRequestToBeSent](https://portswigger.github.io/burp-extensions-montoya-api/javadoc/burp/api/montoya/http/handler/HttpRequestToBeSent.html) and [HttpResponseReceived](https://portswigger.github.io/burp-extensions-montoya-api/javadoc/burp/api/montoya/http/handler/HttpResponseReceived.html). \n\n### Python\n\nPython scripts look like this. Examples can be found in the [examples](examples/python) directory, and for more information about how Python behaves when interacting with Java, see the [GraalVM interop reference](https://www.graalvm.org/latest/reference-manual/python/Interoperability/).\n\n```python\nREQ_FILTER = \"\"\"...\"\"\"\nRES_FILTER = \"\"\"...\"\"\"\n\ndef initialize():\n    print(\"Initialized Python script\")\n\n\ndef cleanup():\n    print(\"Cleaning up Python script\")\n\n\ndef on_request(req):\n    print(f\"{req.method()} - {req.url()}\")\n    return req.withBody(\"Modified\")\n\n\ndef on_response(res):\n    print(f\"{res.statusCode()} - {res.reasonPhrase()}\")\n```\n\n### JavaScript\n\nScripts can be written as either ES6 or CommonJS style modules. Examples can be found in the [examples](examples/js) directory, and for more information about how JavaScript behaves when interacting with Java, see the [GraalVM interop reference](https://www.graalvm.org/latest/reference-manual/js/Interoperability/).\n\nScripts with the file extension `.mjs`, are treated as ES6 modules, where exported handlers look like this:\n\n```javascript\nexport const RES_FILTER = \"...\"\nexport const REQ_FILTER = \"...\"\n\nexport function initialize() {\n    console.log(\"Initialized the JavaScript module\");\n}\n\nexport function cleanup() {\n    console.log(\"Cleaning up JavaScript\");\n}\n\nexport function onRequest(req) {\n    console.log(`${req.method()} - ${req.url()}`)\n    return req.withBody(\"Modified\")\n}\n\nexport function onResponse(res) {\n    console.log(`${res.statusCode()} - ${res.reasonPhrase()}`);\n    return res;\n}\n```\n\nScripts with the extension`.js`, are treated as CommonJS modules, where handlers are exported with `module.exports`:\n\n```javascript\nmodule.exports = {\n    RES_FILTER: \"...\",\n    REQ_FILTER: \"...\",\n    initialize: function() {\n        ...\n    },\n    cleanup: function() {\n        ...\n    },\n    onRequest: function(req) {\n        ...\n    },\n    onResponse: function(res) {\n        ...\n    }\n}\n```\n\n### Addons\n\nScripts may also define handlers using an \"Addon\" style, similar to Mitmproxy. Each addon can define their own filter expressions and handlers. This is useful for organizing complex scripts or sharing addons between different scripts.\n\n**Python**\n```python\nclass AddonOne:\n    REQ_FILTER = \"...\"\n    def on_request(self, req):\n        ...\n\nclass AddonTwo:\n    RES_FILTER = \"...\"\n    def on_response(self, res):\n        ...\n\naddons = [AddonOne(), AddonTwo()]\n```\n\n**JavaScript**\n```javascript\nclass AddonOne {\n    // The methods must be declared this way\n    onRequest = function(req) {\n        ...\n    }\n}\n\nclass AddonTwo {\n    RES_FILTER = \"...\"\n    onResponse = function(res) {\n        ...\n    }\n}\n\nexport const addons = [new AddonOne(), new AddonTwo()]\n```\n\n### Script Globals\n\nScripts have the following global parameters available:\n\n- `api` - a [MontoyaApi]((https://portswigger.github.io/burp-extensions-montoya-api/javadoc/burp/api/montoya/MontoyaApi.html)) instance\n- `helpers` - an instance of [ScriptHelpers](src/main/kotlin/com/carvesystems/burpscript/ScriptHelpers.kt)\n- `log` - an instance of [ScriptLogger](src/main/kotlin/com/carvesystems/burpscript/Logger.kt)\n\n### Printing\n\nScripts can print messages to the Burpscript Extension tab using the `log` object, or with `console.log` in JavaScript, and `print` in Python. Regular messages go to the Output tab, and errors and exceptions go to the Errors tab (see [Managing extensions](https://portswigger.net/burp/documentation/desktop/extensions/managing-extensions))\n\n**Python**\n```python\nlog.info(\"This is an info message\")\nlog.error(\"This is an error message\", Exception(\"Oh no!\")) # Goes to Errors tab\nprint(\"This is an info message\")\n```\n\n**JavaScript**\n```javascript\nlog.info(\"This is an info message\");\nlog.error(\"This is an exception\", new Error(\"On no!\")); // Goes to Errors tab\nconsole.log(\"This is an info message\");\nconsole.error(\"This is an error message\"); // Goes to Errors tab\n```\n\n### Using Java\n\nJava classes can also be imported and used directly from scripts. In python the `java` module can be imported. In JavaScript, the `Java` global object is available. These can be used to import Java types and use them in scripts. \n\n**Python**\n```python\nimport java\n\nHttpParameter = java.type(\"burp.api.montoya.http.message.params.HttpParameter\")\nHttpParameterType = java.type(\"burp.api.montoya.http.message.params.HttpParameterType\")\n\ndef on_request(req):\n    return req.withParameter(\n        HttpParameter.parameter(\"__carve\", \"injected\", HttpParameterType.URL)\n    )\n```\n\n**JavaScript**\n```javascript\nconst HttpParameter = Java.type(\"burp.api.montoya.http.message.params.HttpParameter\")\nconst HttpParameterType = Java.type(\"burp.api.montoya.http.message.params.HttpParameterType\")\n\nexport function onRequest(req) {\n    return req.withParameter(\n        HttpParameter.parameter(\"__carve\", \"injected\", HttpParameterType.URL)\n    )\n}\n```\n\n### Importing\n\nScripts can import other modules that reside in the same directory. Importing 3rd party modules is also supported, however, there are language-specific limitations.\n\n**Python**\n\nHere is an example of importing a utility module that resides in the same directory as the script module:\n\n```python\n# ./myutils.py\ndef do_something():\n    ...\n```\n\n```python\n# ./script.py\nfrom myutils import do_something\n```\n\nPython standard library modules and 3rd party pypi modules can be imported as well. However, not all modules are supported.\nIn particular, modules that depend on native code may fail to import. For the most reliable support, we recommend using [GraalPy](https://www.graalvm.org/python/).\n\nTo allow BurpScript to resolve Python module imports, ensure that the Python interpreter executable, and Python path variables are set in the [BurpScript configuration file](examples/conf.json).\n\n```bash\n$ python -m venv burpscript-env\n$ source burpscript-env/bin/activate\n(burpscript-env) $ pip install pyjwt\n```\n\n```json\n{\n    \"python\": {\n        \"executablePath\": \"/path/to/burpscript-env/bin/python\",\n        \"pythonPath\": \"/path/to/burpscript-env/lib/python3.11/site-packages\"\n    }\n}\n```\n\n```python\n# script.py\nimport jwt\n\ndef on_request(req):\n    token = jwt.encode({\"some\": \"payload\"}, \"secret\", algorithm=\"HS256\")\n    return req.withHeader(\"Authorization\", f\"Bearer {token}\")\n```\n\n**JavaScript (CommonJS)**\n\nCommonJS module style (`.js`) scripts can import other modules using the `require` function.\n\n```javascript\n// ./myutils.js\nmodule.exports = {\n    doSomething: function() {\n        ...\n    }\n}\n```\n\n```javascript\n// ./script.js\nconst { doSomething } = require('./myutils.js')\n```\n\nLimited support for 3rd party NPM modules is also available, however, modules that depend on Node.js built-ins, such as `fs`, and `buffer`, are not supported. See the [GraalVM JavaScript documentation](https://docs.oracle.com/en/graalvm/enterprise/21/docs/reference-manual/js/NodeJSvsJavaScriptContext/#java-libraries) for more information about the limitations. To use 3rd party NPM modules, ensure that the `node_modules` directory is present in the same directory as the script module.\n\n```bash\n$ npm i lodash\n$ ls\nnode_modules/ package.json package-lock.json script.js\n```\n\n```javascript\n// script.js\nconst _ = require('lodash')\n\nmodule.exports = {\n    onRequest: function(req) {\n        return req.withHeader(\"X-RAND\", `${_.random(0, 100)}`)\n    }\n}\n```\n\n**JavaScript (ES6)**\n\nIf the script is written using the ES6 module style (`.mjs`), path-adjacent `.mjs` files can be imported using the `import` statement.\n\n```javascript\n// ./myutils.mjs\nexport function doSomething() {\n    ...\n}\n```\n\n```javascript\n// ./script.mjs\nimport { doSomething } from './myutils.mjs'\n```\n\n\n### Limitations\n\nThere are some limitations with the polyglot API and how values are handled between the script and JVM. If you run into issues with this, it may be difficult to debug exactly what has gone wrong. We're working on helper functions to make these issues easier to deal with. Also, sometimes `import` statements in Python don't work. If you run into such issues, sometimes it may be easier to use `helpers.exec(...)` or `helpers.execStdin(...)`.\n\n## Filter Expressions\n\nFilter expressions are a Lisp-like DSL for selecting requests/responses that should be forwarded on to a script. See [FILTER_EXPRESSIONS.md](FILTER_EXPRESSIONS.md) for documentation.\n\n## Configuration\n\nConfiguration is available via the `${XDG_CONFIG_HOME:-$HOME/.config}/burpscript/conf.json` file. An example config is shown in [the examples dir](examples/conf.json).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fivision-research%2Fburpscript","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fivision-research%2Fburpscript","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fivision-research%2Fburpscript/lists"}