bronzeburner/README.md

<div align="center">
<img src="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) •
[Contributing](#contributing) •
[License](#license)
</div>

## About

*bronzeburner* words

## 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](https://github.com/influxdata/influxdb) (required)
- [Grafana](https://github.com/grafana/grafana) (optional, recommended)
- Docker (recommended)

### Instructions

These 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

TBD

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