🧾🔍 STYX — URL Scanner

STYX is a lightweight URL scanning toolkit powered by the VirusTotal API.
It provides a premium Streamlit dashboard and an interactive CLI menu to quickly classify URLs as:

✅ SAFE • ⚠️ SUSPICIOUS • 🚨 MALICIOUS

---

📋 Table of Contents

• ✨ Key Features
• 🚀 Installation
• 🎮 Usage
  • CLI (Interactive Menu)
  • Dashboard (Streamlit)
• 📁 Project Structure
• 🔐 Security Notes
• 📜 License

---

✨ Key Features

• 🔎 Full scan: submits a URL to VirusTotal and waits for the analysis result
• ⚡ Quick report: fetches the last known VirusTotal report for a URL
• 🧾 Local history stored in data/history.json
• 📄 Reports
  • Download HTML report (Dashboard)
  • Generate HTML + JSON reports (CLI)
  • Export full history as JSON
• 📊 Analytics tab: verdict distribution + basic stats
• 🧠 Clean UX
  • Interactive CLI menu
  • Modern UI dashboard with tabs (Scan / Reports / Analytics)

---

🚀 Setup

1) Clone the repository

git clone https://github.com/yasserbouchaal/styx-url-scanner.git
cd styx-url-scanner

2) Create a virtual environment

python3 -m venv .venv

3) Activate it

source .venv/bin/activate

4) Install dependencies

pip install -r requirements.txt

Debian/Ubuntu (if venv is missing)

sudo apt update
sudo apt install -y python3-venv python3-pip

---

🔑 Configure API Key

1) Create your .env

cp .env.example .env

2) Add your VirusTotal key

Edit .env and paste your key:

VT_API_KEY=YOUR_VIRUSTOTAL_API_KEY

✅ .env is ignored by Git (your key won't be pushed).

---

🎮 Usage

Option 1 — CLI (Interactive Menu)

Run:

python styx_cli.py

CLI actions:

• Full scan (submit + wait)
• Quick report (last known scan)
• Show history
• Generate reports (HTML + JSON)

Reports generated by the CLI are saved in: reports/

Option 2 — Dashboard (Streamlit)

Run locally:

streamlit run app/dashboard.py

Run on a server:

streamlit run app/dashboard.py --server.address 0.0.0.0 --server.port 8501

Open in your browser:

http://SERVER_IP:8501

---

📁 Project Structure

styx-url-scanner/
├─ styx_cli.py                 # Interactive CLI menu
├─ app/
│  └─ dashboard.py             # Streamlit dashboard
├─ core/
│  ├─ virustotal_client.py     # VirusTotal API client
│  ├─ url_tools.py             # URL normalization + VT URL id
│  ├─ history_store.py         # History (data/history.json)
│  └─ report_generator.py      # HTML/JSON report generator
├─ data/
├─ reports/
├─ assets/
└─ requirements.txt

---

🔐 Security Notes

• Do NOT commit your API key. Keep it only in .env.
• VirusTotal has rate limits. If you hit HTTP 429, retry later or use Quick report.
• This tool is intended for defensive analysis and authorized use only.

---

📜 License

This project is licensed under the MIT License.

Author: Yasser BOUCHAAL