From 6c76377e82ea1312e657dcaabe67f291d6d74d46 Mon Sep 17 00:00:00 2001
From: Evan Reichard <evan@reichard.io>
Date: Mon, 22 Mar 2021 13:52:02 -0400
Subject: [PATCH] README update

---
 README.md              | 55 ++++++++++++++++++++++++++++++++++++++----
 docker-compose.yml     |  2 ++
 src/overseer/config.py |  2 +-
 3 files changed, 53 insertions(+), 6 deletions(-)

diff --git a/README.md b/README.md
index 8d3aa68..3cfd70b 100644
--- a/README.md
+++ b/README.md
@@ -4,7 +4,8 @@
 
 ---
 
-A port scanning web interface that allows you to compare results while storing them to a database.
+A port scanning web interface that allows you to compare results while storing
+them to a database.
 
 ## Running
 ```
@@ -18,6 +19,17 @@ docker-compose up -d
 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:
@@ -50,10 +62,11 @@ yarn serve
 # Build resources and auto populate in server static / template resources
 yarn build
 
-# Lint
+# Lint (this is covered by the pre-commit)
 yarn lint
 ```
 
+
 ## Testing
 Once the above development steps are completed, the pytest dependency should
 be installed:
@@ -61,7 +74,39 @@ 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
+```
 
-# Notes
-In a production environment, it would be ideal to setup something like nginx to properly forward
-the `/api/*` routes to the Flask server, and all other endpoints to the static client resources.
+## 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
diff --git a/docker-compose.yml b/docker-compose.yml
index e4701e3..69f9a66 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -3,6 +3,8 @@ services:
   overseer:
     ports:
       - '5000:5000'
+    # environment:
+    #   - DATA_PATH="/tmp/example"
     build: .
     volumes:
       - .:/app
diff --git a/src/overseer/config.py b/src/overseer/config.py
index 7f7f931..efa5c88 100644
--- a/src/overseer/config.py
+++ b/src/overseer/config.py
@@ -13,7 +13,7 @@ class Config:
 
     Attributes
     ----------
-    DATABASE : str
+    DB_TYPE : str
         The specied desired database (default: sqlite)
     DATA_PATH : str
         The path where to store any resources (default: ./)