Black Hat Arsenal Release

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,21 @@
+---
+name: Bug report
+about: Create a report to help improve mole
+title: ''
+labels: bug
+assignees: ztgrace
+
+---
+
+**Describe the bug**
+A clear and concise description of what the bug is.
+
+**To Reproduce**
+Steps to reproduce the behavior:
+
+**Screenshots**
+If applicable, add screenshots to help explain your problem.
+
+**Environment info**
+ - Python version (`python --version`): 
+ - Pip packages(`pip freeze`):

.gitignore

@@ -0,0 +1,12 @@
+*.class
+*.json
+*.pyc
+*.swp
+__pycache__
+burp_venv
+config.yml
+mole.db
+output
+venv
+.idea
+mole.iml

.gitmodules

@@ -0,0 +1,3 @@
+[submodule "third_party/docem"]
+	path = third_party/docem
+	url = https://github.com/ztgrace/docem

README.md

@@ -0,0 +1,107 @@
+# Mole
+
+A framework for identifying and exploiting out-of-band (OOB) vulnerabilities.
+
+## Installation & Setup
+
+### Mole Install
+
+Python >= 3.6
+
+`virtualenv -p /usr/bin/python3 venv`
+
+`source venv/bin/activate`
+
+`./venv/bin/pip3 install -r requirements.txt`
+
+`git submodule update --init --recursive`
+
+Set an API key in `config.yml` (must be the same for the client and server)
+
+### DNS Configuration
+
+You'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.
+
+Mole can be configured to host other configuration options.
+
+#### Mailgun (Optional)
+
+Mailgun requires DNS entries to enable the service: https://help.mailgun.com/hc/en-us/articles/203637190-How-Do-I-Add-or-Delete-a-Domain-
+
+### TLS
+
+Currently 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.
+
+### Burp Suite Extension
+
+The 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.
+
+1. Create a new python2.7 virtualenv for burp/jython, `virtualenv -p /usr/bin/python2.7 burp_venv`
+2. Load the venv, `source ./burp_venv/bin/activate`
+3. Install the required packages, `./burp_venv/bin/pip -r requirements`
+4. Configure the Python Environment by downloading and selecting the jython-standalone jar.
+5. 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.
+
+![burp_python_env](./images/burp_python_env.png)
+
+4. Click Add
+
+![](./images/burp_ext_add_1.png)
+
+5. Set the Extension type to `Python` and select the `mole_burp_extension.py` file from the mole project directory.
+
+![burp_ext_add_2](./images/burp_ext_add_2.png)
+
+6. Click Next and if all goes well, there will be no errors on the load screen.
+
+![burp_ext_success](./images/burp_ext_success.png)
+
+## Configuration
+
+### Token
+
+`domain` - Your custom domain
+
+`length` - Length of the tokens (default 5)
+
+The token character set is ascii upper & 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.
+
+* 1 - 62
+* 2 - 3844
+* 3 - 238328
+* 4 - 14776336
+* 5 - 916132832
+
+`ssl` - Configure payloads for `https` vs `http`
+
+``server` - domain or IP of the Mole token server
+
+`default_tags` - list of default tags to add to all tokens. Useful for per-project/client tokens.
+
+### Server
+
+`api_key` - API key used to authenticate requests to the mole API
+
+`dns_addr` - IP address used to respond to DNS queries
+
+`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`
+
+`static_responses` - list of DNS static response key/value pairs
+
+`web_port` - configure the listening web port
+
+`dns_port` -configure the listening dns port
+
+### Notifications
+
+All 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.
+
+`mailgun` - configure `domain`, `to`, `from`, and `api_key` to enable [mailgun](https://www.mailgun.com/) email notifications
+
+`slack` - `token` and `channel`
+
+`webhook` - generic POST webhook
+
+# Issues/Bugs
+
+I'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.

VERSION

@@ -0,0 +1 @@
+0.1

config.yml.default

@@ -0,0 +1,32 @@
+token:
+  domain: example.com
+  length: 5
+  ssl: false
+  server: 127.0.0.1:80
+  default_tags: 
+    - demo
+server:
+    web_port: 80
+    dns_port: 53
+    db_conn: sqlite:///mole.db
+    api_key: <replace with a unique api key>
+    dns_addr: 1.1.1.1
+    static_responses:
+        ns1.example.com: 1.1.1.1
+        ns2.example.com: 1.1.1.1
+notifications:
+  mailgun:
+    enabled: false
+    domain: 
+    to: 
+    from: 
+    subject: Mole OOB Payload Notification
+    api_key: 
+  slack:
+    enabled: false
+    token:
+    channel:
+  webhook:
+    enabled: false
+    url:
+

lib/__init__.py

@@ -0,0 +1 @@
+__package__ = "mole"

lib/banner.py

@@ -0,0 +1,23 @@
+# -*- coding: utf-8 -*-
+from .util import get_version
+
+
+def banner():
+
+    logo = """
+
+ ███▄ ▄███▓ ▒█████   ██▓    ▓█████ 
+▓██▒▀█▀ ██▒▒██▒  ██▒▓██▒    ▓█   ▀ 
+▓██    ▓██░▒██░  ██▒▒██░    ▒███   
+▒██    ▒██ ▒██   ██░▒██░    ▒▓█  ▄ 
+▒██▒   ░██▒░ ████▓▒░░██████▒░▒████▒
+░ ▒░   ░  ░░ ▒░▒░▒░ ░ ▒░▓  ░░░ ▒░ ░
+░  ░      ░  ░ ▒ ▒░ ░ ░ ▒  ░ ░ ░  ░
+░      ░   ░ ░ ░ ▒    ░ ░      ░   
+       ░       ░ ░      ░  ░   ░  ░
+                                   
+v{0}
+Out of Band Payload Framework
+Black Hat Arsenal 2020 Edition
+""".format(get_version())
+    print(logo)

lib/config.py

@@ -0,0 +1,48 @@
+import os
+import sys
+import yaml
+
+
+class Config(object):
+    def __init__(self, conf_file='config.yml'):
+        self.path = os.path.join(os.path.dirname(os.path.abspath(__file__)), '../', conf_file)
+        conf = open(self.path, 'r').read()
+
+        # Support Python 2 and 3 for Burp
+        if float(sys.version[0:3]) >= 3.0:
+            conf = yaml.safe_load(conf)
+        else:
+            conf = yaml.load(conf)
+
+        # Token config
+        self.token_domain = conf['token']['domain']
+        self.token_length = int(conf['token']['length'])
+        if conf['token']['ssl']:
+            self.token_protocol = 'https'
+        else:
+            self.token_protocol = 'http'
+        self.token_server = conf['token']['server']
+        self.tags = conf['token']['default_tags']
+
+        # Server config
+        self.server_web_port = conf['server']['web_port']
+        self.server_dns_port = conf['server']['dns_port']
+        self.server_db_conn = conf['server']['db_conn']
+        self.server_api_key = conf['server']['api_key']
+        self.dns_addr = conf['server']['dns_addr']
+        self.static_responses = conf['server'].get('static_responses', list())
+
+        # Mailgun
+
+        self.mailgun = conf['notifications']['mailgun']
+
+        # Slack
+        self.slack = conf['notifications']['slack']
+
+        # Webhook
+        self.webhook = conf['notifications']['webhook']
+
+
+        self.debug = False
+        self.output = 'output'
+        self.notifications = list()

lib/models/__init__.py

@@ -0,0 +1,18 @@
+from sqlalchemy import create_engine
+from sqlalchemy.orm import scoped_session, sessionmaker
+from sqlalchemy.ext.declarative import declarative_base
+
+global mole_config
+engine = create_engine('sqlite:///mole.db', convert_unicode=True)
+#engine = create_engine(mole_config.db_conn, convert_unicode=True)
+db = scoped_session(sessionmaker(autocommit=False,
+                                         autoflush=False,
+                                         bind=engine))
+Base = declarative_base()
+Base.query = db.query_property()
+
+# Import subclasses
+from lib.models.event import Event
+from lib.models.token import Token
+
+Base.metadata.create_all(bind=engine)

lib/models/event.py

@@ -0,0 +1,22 @@
+from lib.models import *
+from sqlalchemy import Column, DateTime, ForeignKey, Integer, String, Text
+from sqlalchemy.orm import relationship, backref
+
+
+class Event(Base):
+    __tablename__ = 'events'
+
+    id = Column(Integer, primary_key=True)
+    type = Column(String(256))
+    timestamp = DateTime()
+
+    token_id = Column(Integer, ForeignKey('tokens.id'),
+                      nullable=False)
+    token = relationship('Token',
+                         backref=backref('events', lazy=True))
+
+    # Context about the event such as source IP address
+    context = Column(Text)
+
+    def __repr__(self):
+        return '<Event token:%s, ts:%s>' % (self.token, self.timestamp)

lib/models/token.py

@@ -0,0 +1,14 @@
+from lib.models import *
+from sqlalchemy import Column, DateTime, Integer, String, Text
+
+
+class Token(Base):
+    __tablename__ = 'tokens'
+
+    id = Column(Integer, primary_key=True)
+    token = Column(String(256), unique=True)
+    context = Column(Text)
+    created = DateTime()
+
+    def __repr__(self):
+        return '<Token %s>' % self.token

lib/plugins/listpluginmixin.py

@@ -0,0 +1,28 @@
+import os
+import re
+from .plugin import Plugin
+from ..trackingtoken import TrackingToken
+
+
+class ListPluginMixin(Plugin):
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+
+    def build(self):
+        payloads = list()
+        i = 0
+
+        # Loop through the files in the configured directory
+        with open(os.path.join(self.path, self.list), 'r') as fin:
+            for line in fin:
+                line = line.strip()
+                if not re.match(r'^#', line) and not re.match(r'^$', line):
+                    tags = [self.name, '{}-payloads{}'.format(self.list, i)]
+                    t = TrackingToken(config=self.config, tags=tags)
+                    payload = line.replace('<TOKEN>', t.value)
+                    payload = payload.replace('<DOMAIN>', t.config.token_domain)
+                    payload = payload.replace('<PROTO>', t.config.token_protocol)
+                    payloads.append(payload)
+                    i += 1
+
+        return payloads

lib/plugins/notification.py

@@ -0,0 +1,10 @@
+class Notification(object):
+    def __init__(self, *args, **kwargs):
+        for k, v in kwargs.items():
+            setattr(self, k, v)
+
+    def notify(self, message: str):
+        raise NotImplementedError
+
+    def isEnabled(self):
+        return self.config.__dict__.get(self.__class__.__name__.lower())['enabled']

lib/plugins/plugin.py

@@ -0,0 +1,7 @@
+class Plugin(object):
+    def __init__(self, *args, **kwargs):
+        for k, v in kwargs.items():
+            setattr(self, k, v)
+
+    def build(self):
+        raise NotImplementedError