From 2156c6f2b47107e89efa937d37b9b5185f995f2d Mon Sep 17 00:00:00 2001
From: Elijah R <elijah@computernewb.com>
Date: Fri, 26 Jul 2024 00:46:12 -0400
Subject: [PATCH] fill in README and comment config.example.toml

---
 README.md           | 44 +++++++++++++++++++++++++++++++++++++++++++-
 config.example.toml | 10 ++++++++++
 2 files changed, 53 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index be0480e..367b640 100644
--- a/README.md
+++ b/README.md
@@ -1 +1,43 @@
-# whitelister-eternal
+# Whitelister ETERNAL
+
+A node.js server that can be used with Nginx Auth Requests to filter out VPN/Proxy/Datacenter IPs using a couple methods
+
+## Jumpstart
+
+1. Clone the repo
+2. Copy `config.example.toml` to `config.toml` and fill out necessary fields
+3. Install dependencies: `yarn`
+4. Build the TypeScript: `yarn build`
+5. Run it: `yarn serve` or `node ./dist/index.js`
+
+## Nginx setup
+
+This is designed to be used with Nginx Auth Requests. You can include it in your config as follows:
+
+Make SURE that if your site is proxied with Cloudflare that you comment and uncomment the indicated lines, or you will be vulnerable to IP spoofing due to the non-standard way Cloudflare sets the X-Forwarded-For header.
+
+```nginx
+upstream whitelister {
+    server 127.0.0.1:3000; # If you changed the port in config.toml, change here too
+}
+
+server {
+    # ...
+    location /whitelister/ {
+        internal;
+        
+        proxy_pass http://whitelister/auth;
+
+        # Comment this if you use Cloudflare
+        proxy_set_header X-Forwarded-For $remote_addr;
+
+        # Uncomment this if you do NOT use Cloudflare
+        # proxy_set_header X-Forwarded-For $http_cf_connecting_ip;
+    }
+
+    location /path-i-want-protected/ {
+        # ...
+        auth_request /whitelister/;
+    }
+}
+```
\ No newline at end of file
diff --git a/config.example.toml b/config.example.toml
index a3d21a8..c7fed31 100644
--- a/config.example.toml
+++ b/config.example.toml
@@ -1,28 +1,38 @@
 [http]
+# IP address to bind to. This should almost always be 127.0.0.1
 host = "127.0.0.1"
+# Port to bind to
 port = 3000
 
 [whitelister]
+# Fail if a test returns a warning. This is not implemented by any tests yet.
 failOnWarn = true
 
 [mysql]
+# MySQL connection information, used to cache IP addresses and results
 host = "127.0.0.1"
 user = "whitelister"
 password = "hunter2"
 database = "whitelister"
 
 [cloudflare]
+# If enabled, any IP that fails a test will be added to the specified Cloudflare list
 enabled = true
 apiKey = ""
 accountID = ""
 listID = ""
 
 [tests.asn]
+# Test to check if an IP is in a list of bad ASNs
 enabled = true
+# File containing a list of ASNs to blacklist
 blacklistFile = "./asn_blacklist"
+# Directory to cache the MaxMind ASN database in
 maxmindDirectory = "./maxmind/"
+# https://www.maxmind.com/en/accounts/current/license-key
 maxmindAccountID = ""
 maxmindLicenseKey = ""
 
 [tests.spur]
+# Test to check if an IP is detected by https://spur.us
 enabled = true
\ No newline at end of file