bronzeburner/README.md

<div align="center">
<img src="img/bronzeburner.png" alt="bronzeburner logo">

# bronzeburner

**bronzeburner** is a humble network scanner

use it to monitor your enterprise's ports over time<br/>

[About](#about) •
[Installation](#installation) •
[Example](#example) •
[FAQ](#faq) •
[Contributing](#contributing) •
[License](#license)
</div>

## 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](https://github.com/RustScan/RustScan) (required, in $PATH)
- [InfluxDB 2.x](https://github.com/influxdata/influxdb) (required)
- [Grafana](https://github.com/grafana/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](https://github.com/pyenv/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/](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.

```bash
❯ 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

<img src="img/bb_execution.png" alt="command line execution of bronzeburner showing various open ports and details for an ip address">

## 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.