113 lines
5.1 KiB
Markdown
113 lines
5.1 KiB
Markdown
<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
|
||
|
||
### CLI
|
||
|
||
<img src="img/bb_execution.png" alt="command line execution of bronzeburner showing various open ports and details for an ip address">
|
||
|
||
### 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.
|
||
|
||
<img src="img/influxdb.png" alt="influxdb interface showing port information imported into a time series database format for querying">
|
||
|
||
## 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.
|