bronzeburner/README.md

bronzeburner

bronzeburner is a humble network scanner

use it to monitor your enterprise's ports over time

About • Installation • Example • FAQ • Contributing • License

About

bronzeburner is a utility for any sized corporation to help manage exposed services and ports against threats both internal and exterinal. As firewalls are modified or replaced, rules can be misconfigured so that addresses or ports are available externally that perhaps shouldn't be.

Initially, bronzeburner was going to be a passive perimeter monitor using nfqueue (and alternatively, XDP) to inspect communications. After implementing this, I realized it did not meet the requirements for the assignment which requires a proactive approach. bronzeburner was rewritten as a classic network scanner which instruments rustscan, expertly parses its output, and inserts it into a time series database most information security workers should be familiar with.

This instrumentation approach is a bit more basic but enables users to customize their querying, alerting, and filtering requirements themselves using InfluxDB, Grafana, or any other data sink. As a traditional scanner, it can be run from any location within a network or even from outside, perhaps from a remote cloud VM.

Installation

This project was authored for use with Pypy3.10 for performance reasons, but will likely run fine with any full Python implementation. Unfortunately, this means several useful libraries are yet incompatible (e.g., uvloop).

Requirements & Recommendations

• RustScan (required, in $PATH)
• InfluxDB 2.x (required)
• Grafana (optional, recommended)
• Docker (recommended)

Getting Started

These basic instructions assume you're running a Linux or macOS system. If you aren't, the instructions can easily be adapted. If you don't already use pyenv, look into using it to manage your Python versions. Use it to install Pypy3.10 or install it manually. For macOS users, Pypy3.10 can be installed with brew install pypy3.10.

Clone this repository with git clone .... Browse to the newly created project directory with cd bronzeburner. Create a new virtual Python environment with pypy3.10 -m venv venv and activate it with source venv/bin/activate. Install bronzeburner and its dependencies with pip install ..

Install Docker if you don't already use it. Create a persistent directory to store your data (i.e., /opt/influxdb). To run an InfluxDB instance, run docker run -v /opt/influxdb:/var/lib/influxdb2 -p 8086:8086 influxdb:2.7.1-alpine. Browse to http://127.0.0.1:8086/ and set up your instance. Create a new API key with write access to your new org's new bucket and note it down.

You're ready to run bronzeburner.

❯ bronzeburner -h
usage: bronzeburner [-h] -a ADDRESS -u URL -o ORG -b BUCKET -t TOKEN

A humble network scanner

options:
  -h, --help            show this help message and exit
  -a ADDRESS, --address ADDRESS
                        IP address or CIDR range to scan
  -u URL, --url URL     InfluxDB server URL
  -o ORG, --org ORG     InfluxDB organization
  -b BUCKET, --bucket BUCKET
                        InfluxDB bucket
  -t TOKEN, --token TOKEN
                        InfluxDB token

Decide on a target. bronzeburner accepts IPv4 addresses and CIDR ranges as address targets but can be extended to include additional options. See the example execution below.

Example

CLI

InfluxDB Simple Table

Below is an example of the data inserted into InfluxDB by bronzeburner. Grafana can be integrated with InfluxDB to plot timelines of ports for each host or to alert on newly observed hosts or ports.

FAQ

This scans all ports? Isn't that slow?

It can be if you use nmap. RustScan, which bronzeburner uses, multiprocesses nmap and is capable of scanning all ports on a single host in as fast as three seconds!

I see timestamp data is saved in the time series DB, but I'd also like some logging. What's my best bet?

bronzeburner logs comprehensively to STDOUT, so simply forward the output of bronzeburner to a file with bronzeburner <options> > out.log.

Contributing

If you would like to contribute to this project, feel free to submit a pull request or open an issue on GitHub.

This tool was written as part of my coursework for INFA 735 - Offensive Security at Dakota State University. Consequently, I may choose not to maintain this tool beyond the length of the course.

License

This project is licensed under AGPL 3.0. See the LICENSE file for details.