---

A port scanning web interface that allows you to compare results while storing them to a database.

Running

# Be sure image is built
docker-compose build

# Run compose in background. Service accessible via localhost:5000
docker-compose up -d

# Alternatively, in virtualenv
overseer run

Configuration

The application can be configured using environment variables. The following vars are available:

Environment Variable	Description	Default
DB_TYPE	Database type (memory / sqlite)	sqlite
DATA_PATH	Path to store the database	./

You can find a commented out example in the docker-compose.yml file.

Developing

Once you have installed the setup.py and overseer[dev] dependencies, you can run pre-commit to lint all server and client files:

pre-commit run --all-files

Server

# Setup virtual env
python3 -m venv overseer_venv
. overseer_venv/bin/activate

# Link overseer to working directory & install dev dependencies
python setup.py develop easy_install overseer[dev]

# Can use to run the server
overseer run

Client

# Change directory
cd ./src/overseer_client

# On the fly reloading (no server access)
yarn serve

# Build resources and auto populate in server static / template resources
yarn build

# Lint (this is covered by the pre-commit)
yarn lint

Testing

Once the above development steps are completed, the pytest dependency should be installed:

pytest

If you want to quickly test the scanners ability, you can spin up some TCP listeners:

# Listens on ports 60 -> 70
for i in {60..70}; do (nc -l "$i" &) ; done

Design

Server

The server is written in Python and uses Flask and SQLAlchemy. I wanted to have the capability to extend to another database fairly easily if so. This gave me that. I also used Flask's Blueprint to allow easy versioning of the API.

In addition to regular POST / GET API endpoints, I added WebSocket support. This allows us to see the progress of the scan without polling, and makes the overrall user experience better.

For the scanner, we have the ScanManager and the Scanner class itself. The manager is responsible initiating new scans, publishing the status to the websocket, and committing status changes to the Database.

The scanner itself threads the TCP and UDP scan. It also parses the nmap-payloads file to build a dictionary of UDP payloads to check for responses to.

Client

The client is writting in Vue.js framework. This makes maintaining easier and provides us with a very reactive interface.

Some capabilities:

• Notification drawer with live progress and clickable notifications
• Live TCP / UDP / Total progress bars
• View all scans for a capability and see port results come in on the fly
• Compare any scan with its preceding scan
• Clicking the target (host / ip) brings you to all scans