{"id":13842926,"url":"https://github.com/ztgrace/mole","last_synced_at":"2025-07-11T17:32:18.551Z","repository":{"id":72940723,"uuid":"222960408","full_name":"ztgrace/mole","owner":"ztgrace","description":"Mole is a framework for identifying and exploiting out-of-band application vulnerabilities.","archived":false,"fork":false,"pushed_at":"2020-08-06T15:19:50.000Z","size":139,"stargazers_count":56,"open_issues_count":0,"forks_count":18,"subscribers_count":5,"default_branch":"master","last_synced_at":"2024-11-21T14:38:07.586Z","etag":null,"topics":["appsec","burp-extensions","infosec","oob","penetration-testing","python","security-tools","xss","xxe"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ztgrace.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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}},"created_at":"2019-11-20T14:49:16.000Z","updated_at":"2024-08-12T19:55:02.000Z","dependencies_parsed_at":"2024-02-03T03:55:55.007Z","dependency_job_id":"b4cfe4c3-cad9-4f2e-a740-848db753e8ee","html_url":"https://github.com/ztgrace/mole","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/ztgrace/mole","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ztgrace%2Fmole","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ztgrace%2Fmole/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ztgrace%2Fmole/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ztgrace%2Fmole/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ztgrace","download_url":"https://codeload.github.com/ztgrace/mole/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ztgrace%2Fmole/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":264862495,"owners_count":23674985,"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":["appsec","burp-extensions","infosec","oob","penetration-testing","python","security-tools","xss","xxe"],"created_at":"2024-08-04T17:01:51.257Z","updated_at":"2025-07-11T17:32:18.236Z","avatar_url":"https://github.com/ztgrace.png","language":"Python","funding_links":[],"categories":["Python","Python (1887)"],"sub_categories":[],"readme":"# Mole\r\n\r\nA framework for identifying and exploiting out-of-band (OOB) vulnerabilities.\r\n\r\n## Installation \u0026 Setup\r\n\r\n### Mole Install\r\n\r\nPython \u003e= 3.6\r\n\r\n`virtualenv -p /usr/bin/python3 venv`\r\n\r\n`source venv/bin/activate`\r\n\r\n`./venv/bin/pip3 install -r requirements.txt`\r\n\r\n`git submodule update --init --recursive`\r\n\r\nSet an API key in `config.yml` (must be the same for the client and server)\r\n\r\n### DNS Configuration\r\n\r\nYou'll need to configure the DNS records in your registrar to point to your mole server. Minimally, you'll need an `A` record for the name server and an `NS` record configured.\r\n\r\nMole can be configured to host other configuration options.\r\n\r\n#### Mailgun (Optional)\r\n\r\nMailgun requires DNS entries to enable the service: https://help.mailgun.com/hc/en-us/articles/203637190-How-Do-I-Add-or-Delete-a-Domain-\r\n\r\n### TLS\r\n\r\nCurrently Mole does not support TLS natively. To implement TLS, use a reverse proxy such as [nginx](https://docs.nginx.com/nginx/admin-guide/security-controls/terminating-ssl-http/) to terminate the TLS connection and forward traffic to the Mole server.\r\n\r\n### Burp Suite Extension\r\n\r\nThe Burp Suite Extension requires a separate Python 2.7 virtual environment due to the latest version of Jython only supporting 2.7. Below are the instructions for setting up the virtual environment and configuring the Extension.\r\n\r\n1. Create a new python2.7 virtualenv for burp/jython, `virtualenv -p /usr/bin/python2.7 burp_venv`\r\n2. Load the venv, `source ./burp_venv/bin/activate`\r\n3. Install the required packages, `./burp_venv/bin/pip -r requirements`\r\n4. Configure the Python Environment by downloading and selecting the jython-standalone jar.\r\n5. Set the \"Folder for loading modules\" to the full path to `burp_venv/lib/python2.7/site-packages` that was created in steps 1-3.\r\n\r\n![burp_python_env](./images/burp_python_env.png)\r\n\r\n4. Click Add\r\n\r\n![](./images/burp_ext_add_1.png)\r\n\r\n5. Set the Extension type to `Python` and select the `mole_burp_extension.py` file from the mole project directory.\r\n\r\n![burp_ext_add_2](./images/burp_ext_add_2.png)\r\n\r\n6. Click Next and if all goes well, there will be no errors on the load screen.\r\n\r\n![burp_ext_success](./images/burp_ext_success.png)\r\n\r\n## Configuration\r\n\r\n### Token\r\n\r\n`domain` - Your custom domain\r\n\r\n`length` - Length of the tokens (default 5)\r\n\r\nThe token character set is ascii upper \u0026 lower, and digits. The length can be modified to meet needs such as constrained space for a payload. The number of tokens per length is listed below.\r\n\r\n* 1 - 62\r\n* 2 - 3844\r\n* 3 - 238328\r\n* 4 - 14776336\r\n* 5 - 916132832\r\n\r\n`ssl` - Configure payloads for `https` vs `http`\r\n\r\n``server` - domain or IP of the Mole token server\r\n\r\n`default_tags` - list of default tags to add to all tokens. Useful for per-project/client tokens.\r\n\r\n### Server\r\n\r\n`api_key` - API key used to authenticate requests to the mole API\r\n\r\n`dns_addr` - IP address used to respond to DNS queries\r\n\r\n`db_conn` - [SQLAlchemy](https://www.sqlalchemy.org/) [database URL](https://docs.sqlalchemy.org/en/13/core/engines.html). Default is a SQLite db in the root directory `sqlite:///mole.db`\r\n\r\n`static_responses` - list of DNS static response key/value pairs\r\n\r\n`web_port` - configure the listening web port\r\n\r\n`dns_port` -configure the listening dns port\r\n\r\n### Notifications\r\n\r\nAll notifications have an `enabled` flag that determines whether or not to trigger the notification on an interaction. Each notification plugin has its own configuration items.\r\n\r\n`mailgun` - configure `domain`, `to`, `from`, and `api_key` to enable [mailgun](https://www.mailgun.com/) email notifications\r\n\r\n`slack` - `token` and `channel`\r\n\r\n`webhook` - generic POST webhook\r\n\r\n# Issues/Bugs\r\n\r\nI'm sure there are many, please create a new [issue](https://github.com/ztgrace/mole/issues) and fill out the template as best as you can for quick triage.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fztgrace%2Fmole","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fztgrace%2Fmole","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fztgrace%2Fmole/lists"}