Darryl Nixon
e3072150d9
* feat(cli.py): add command line arguments and async main function * feat(influx.py): add InfluxDB class for handling InfluxDB operations * feat(logs.py): add logger configuration * feat(scan.py): add functions for running rustscan and parsing its output * feat(validation.py): add function for validating CIDR or IPv4 address * fix(pyproject.toml): update dependencies * fix(README.md): change 'Examples' to 'Example' * fix(bronzeburner.png): update image file * fix(cli.py): update main function * fix(scan.py): update run_rustscan function to use asyncio *
82 lines
3 KiB
Markdown
82 lines
3 KiB
Markdown
<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.
|