first commit

Readme.md

@@ -0,0 +1,92 @@
+# URL Sandbox
+
+A lightweight web-based sandbox for analyzing websites and domains.  
+It performs WHOIS lookups, GeoIP enrichment, script/form inspection, and provides analyst-friendly output.
+
+---
+
+## 🚀 Features
+
+- **Domain & IP Enrichment**
+  - WHOIS lookups with fallback to raw text when fields are missing
+  - Explicit handling of privacy-protected WHOIS records (`N/A` or `Possible Privacy`)
+  - GeoIP (City, Region, Country, Latitude/Longitude)
+  - ASN, ISP, and network details
+- **Flagged Content Analysis**
+  - Suspicious script detection
+  - Suspicious form detection
+  - Nested bullet-style reporting for clarity
+- **Improved UX**
+  - Automatic addition of `http://`, `https://`, and `www.` if only a domain is provided
+  - Modal spinner to indicate background analysis (`Analyzing website…`)
+- **Resilient GeoLite2 Database Management**
+  - Downloads the MaxMind GeoLite2-City database on first startup
+  - Checks file age and only re-downloads if older than **14 days** (configurable via environment variable)
+
+---
+
+## ⚙️ Setup Instructions
+
+### 1. Clone the Repository
+```bash
+git clone https://github.com/yourusername/url-sandbox.git
+cd url-sandbox
+```
+
+### 2. Create a MaxMind Account & License Key
+1. Go to [MaxMind GeoLite2](https://dev.maxmind.com/geoip/geolite2-free-geolocation-data)
+2. Sign up for a free account
+3. Navigate to **Account > Manage License Keys**
+4. Generate a new license key
+
+### 3. Configure Environment Variables
+All environment variables are loaded from a `.env` file.  
+
+1. Copy the sample file:  
+```bash
+   cp .env.example .env
+````
+
+2. Edit `.env` and set your values (see [`.env.example`](./.env.example) for available options).
+
+Make sure to add your **MaxMind License Key** under `MAXMIND_LICENSE_KEY`.
+
+
+### 4. Run with Docker Compose
+```bash
+docker-compose up --build
+```
+
+This will:
+- Build the app
+- Download the GeoLite2 database if not present or too old
+- Start the web interface
+
+---
+
+## 📝 Example Output
+
+**WHOIS Info**
+- Registrar: MarkMonitor, Inc.
+- Organization: Possible Privacy
+- Creation: 1997-09-15
+- Expiration: 2028-09-14
+
+**GeoIP Info**
+- IP: 172.66.159.20
+  - City: N/A  
+  - Region: N/A  
+  - Country: United States  
+  - Coordinates: (37.751, -97.822)
+  - ASN: 13335  
+  - ISP: Cloudflare, Inc.
+
+---
+
+## 📌 Roadmap
+See [Next Steps Checklist](docs/roadmap.md) for planned features:
+- Improved UI templates
+- Artifact cleanup
+- Proxy support (optional)
+
+---